I loathe PHP's docs for two reasons: - the colour choice; - the comments. The colour choice for code examples is orange on gray. This is almost impossible to

I loathe PHP's docs for two reasons: - the colour choice; - the comments. The colour choice for code examples is orange on gray. This is almost impossible to read for colour-blind people. I have to squint to make out each character. I can't get in to a flow and read the code, I have to decode each character then put them together to read the snippet in its entirety. I don't think user-land comments have any place in documentation. The docs form part of the official specs for the language and, personally, I find user comments create too much unintentional confusion. You often find well-intentioned amateurs make basic errors in PHP's doc examples. User comments can be great for examples, but they belong in a separate place, say, a wiki. An example of good docs IMO is Python's. A nice helpful topic bar on the left, and careful docs on the right.