31–40 of 47 posts
Flask's documentation is my favorite. I sat down and read all of it one night just because it was so beautiful and readable. http://flask.pocoo.org/
Thought I'd get to Flask before Steve, but clearly I was mistaken. Another vote for Flask. Gorgeous.
jQuery and CakePHP have been very helpful in the past. http://docs.jquery.com/Main_Page http://book.cakephp.org/ Also, the PHP documentation is very good. The layout could be better but it's kept really simple with lots of examples to help you out. http://www.php.net/manual/en/
- I'm too busy
- It should already be there, this is a common problem
- I don't know enough to edit
- How do I make an account
Good documentation for a community is hard.
http://us3.php.net/strstr -> The php docs have one redeeming quality that I wish all of them had: comments! Whenever there is odd behavior, a gotcha, a pitfall, it's always in the comments. No need to trawl through blogs and mailing lists.
I agree, and have an additional comment: If the comments become part of the documentation, then you need to ruthlessly edit them to remove incorrect advice, duplication, and redundancy. If you simply leave everything there forever, then the comments become worthless. Integrity of information is everything.
jQuery and CakePHP have been very helpful in the past. http://docs.jquery.com/Main_Page http://book.cakephp.org/ Also, the PHP documentation is very good. The layout could be better but it's kept really simple with lots of examples to help you out. http://www.php.net/manual/en/
Flask's documentation is my favorite. I sat down and read all of it one night just because it was so beautiful and readable. http://flask.pocoo.org/
Another vote for Flask. The Sintra docs are also quite good. http://www.sinatrarb.com/documentation
http://us3.php.net/strstr -> The php docs have one redeeming quality that I wish all of them had: comments! Whenever there is odd behavior, a gotcha, a pitfall, it's always in the comments. No need to trawl through blogs and mailing lists.
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.
(But if I remember correctly, they don't rock in all browsers.)
A step-by-step example helps alot.
Earlier quoted context omitted.
I agree, and have an additional comment: If the comments become part of the documentation, then you need to ruthlessly edit them to remove incorrect advice, duplication, and redundancy. If you simply leave everything there forever, then the comments become worthless. Integrity of information is everything.
Agreed. It would also be worth considering using Stack Overflow-style voting for comments.