[josteink]

PHP is extremely well documented and it's been around so long that it's easy to find solutions on the web.

I can agree that PHP is documented. That it is well documented however is something I'm very much willing to argue against.

PHP has string-operations documented to be "binary-safe" without ever saying what that is supposed to mean, if it's good (it's not), if it's bad (yes, yes, yes it is) and why you should have an opinion on that at all. Nothing about that. "Binary-safe" is not defined anywhere. It just "notes" that all these operations which should operate on text is "binary-safe". And "safe" makes it sound like a good feature, right?

Documentation like this is probably written by people who have no idea what a character encoding is and thinks that being able to strpos() on raw byte-data is a "cool feature", without understanding that text and it's encoded representation are two very different things.

Basically, the documentation is written by people lacking any deep understanding of the subject they are covering, and they pass their confusion on to whoever may be unfortunate enough to stumble upon it.

So... Is bad documentation better than no documentation? I don't know. Maybe? Still: PHP documentation, good or bad, represents the blind leading the blind.

If you want "extremely well documented", head over to MSDN and check the .net docs. It's systematic, it's consistent and it's thorough. It's written by people who understand the difference between Unicode, UTF8, text and bytes. Or whatever else the subject you are reading about covers.

But people peddling in PHP wouldn't know that, because they wouldn't want to go too far outside their comfort-zones, and hey, they definitely wouldn't want to look at anything done by Microsoft.

[krob]

@josteink, you don't really understand what good documentation is do you. A large amount of PHP documentation provides context in which you may effectively implement a piece of code by providing "sufficient" examples. A grenade I can almost guarantee you probably comes with documentation, but probably a warning which states when you pull the pin, it will blow up. PHP will not blow up the world, or blow your hands off. The documentation does not have to be "perfect". PHP has changed web development in many positive ways, by increasing what could be done via simplicity using what you might call poor documentation. It has sufficed enough that good developers found it sufficient to build large complex code-bases which they could both build on and make money from. Much of MSDN library is created from internal comment-style documentation automation(JavaDoc,PHPDoc, XML Comments). MSDN will often times lack easily readable code-samples, and provide enough context in which you may actually use a library. Just because you define a prototype with long naming conventions doesn't mean Joe schmuck has a clue. PHP examples are generally not obtuse, or obfuscated to newbies. It's the "I'm going to show you how to hunt fish" and nobody said it had to be pretty. MSDN has gotten better over the years, but there are still many areas in the many libraries hosted on there which don't have "even good enough" documentation to help you to the most basic things.

[iridium]

It doesn't hurt that Microsoft is able to hire the best engineering grads, pay them 100k, and convince them that writing documentation for .NET is a better deal than building some pseduo cool product somewhere else at half the pay.

The very small percentage of php developers who have ever had to deal with binary data probably had their hands burnt enough to figure out what binary safe was. While I'm not arguing that documentation should have vague references, its not that hard of a tradeoff between just mentioning something that should be explained over pages, as opposed to not having it there at all.

Plus, the comments section makes it very useful to have examples and clarifications. Its not as bad as you make it out to be.

[gizzlon]

Agreed.. I like that they often have examples to get you started quickly, but a lot is simply left out. Especially the quirks, and php has a lot of them.

I'm used to dealing with perl 5, which has quirks of it's own, but at least their documented (a little too much sometimes). I learn a lot about many things by reading the perl docs.

Here's "Gory details of parsing quoted constructs" (no that I have read it..)

http://perldoc.perl.org/perlop.html#Gory-details-of-parsing-...