I've been helping out a few open source projects with documentation, and would love to flip through what you consider good and bad documentation. I'll keep the request wide since I'm interested in different forms (API docs, lib docs, quick start guides, reference docs).
I've always loved the PHP.net site for documentation.
Let's say we wanted to know about the `explode` function, right at the top of their page is a search box. Type in the function and a dropdown populates with a brief description of the function, adding confidence that you're on the right result.
You click the function and right there it gives you the function signature in easily readable text that's color coded. Just at a glance I know that explode will return an array, I must pass it a delimiter first, then the string I want to split and then there is an optional argument in square braces.
If that wasn't enough it goes on to explain each parameter down below as well as the return values.
Further down is the change log on what changed between versions.
Next up are what really makes the PHP documentation shine for me: examples.
Succinct and to the point examples with comments that have always been enough to get me started with the basics.
This would have been good enough, but they go a step further to give me related functions in the "See Also" section. Sometimes I'm looking for one function, but then find a function that can do it better, or I realize that hey after I perform this action, I'm probably going to need to use another one of these related functions such as the `implode` function.
User comments at the bottom are also great! They are usually insightful and have been very helpful in the past.
The writing for classes and extensions is also equally as good: well written, quick start guides, installation settings for Windows and Linux.
I've always felt that the website was very user friendly and accessible. When you go to the landing page you're not overwhelmed with information. Just a quick blurb about what PHP is, the news of releases, easy to find download options, and documentation and search are all above the fold and prominently featured.
One of the really nice things about PHP.net in particular is that you can go to any function name as a root directory on the website and it will look it up, e.g. http://php.net/explode will go right to the explode doc. This works for root functions as well as classes and most keywords.
Good : Google's documentation - It nicely break downs documentation into 3 or 4 simple tabs(guides, reference and samples). Left panel has breakdown of page related to tab , right panel has more detailed view of the page itself. This kind of provides 3-indices to entire documentation. (eg: https://goo.gl/7ZIuX)
Most of documentation is simple enough to understand with examples and highlighted with right colors wherever it is required (I feel color highlighting remains under appreciated in documentation). And also one can invoke apis and play a bit.
ZeroMQ: awesome docs (i recommend also the ZeroMQ O'Reilly book by the MH, the library author) particularly for a library with a broad range of functionality not easily described by a single technical category.
PostgreSQL's documentation is an excellent reference - you can learn SQL, and learn it well, just from the manual. It is pretty dry, though.
OpenBSD's man pages are also excellent reference documents. One really great thing is that they document all possible behaviors, which is disturbingly rare for (e.g.) Python libraries.
If I could piggyback on this question, I'd really be interested in any reading material or podcasts specifically about technical writing. I'd like to get better at it, but most of what I've seen is just general style guides, not concrete information about the how and the why of organizing technical information.
I remember years ago reading through the Vyatta Firewall Linux Distribution's docs & thinking about how well they were written. Haven't looked at it for nearly a decade by now though.
Forgot to add to my original request: For yourself, what makes something "good documentation"? What makes bad documentation? Are there things you wish people did more of or less of?
Let's say we wanted to know about the `explode` function, right at the top of their page is a search box. Type in the function and a dropdown populates with a brief description of the function, adding confidence that you're on the right result.
You click the function and right there it gives you the function signature in easily readable text that's color coded. Just at a glance I know that explode will return an array, I must pass it a delimiter first, then the string I want to split and then there is an optional argument in square braces.
If that wasn't enough it goes on to explain each parameter down below as well as the return values.
Further down is the change log on what changed between versions.
Next up are what really makes the PHP documentation shine for me: examples.
Succinct and to the point examples with comments that have always been enough to get me started with the basics.
This would have been good enough, but they go a step further to give me related functions in the "See Also" section. Sometimes I'm looking for one function, but then find a function that can do it better, or I realize that hey after I perform this action, I'm probably going to need to use another one of these related functions such as the `implode` function.
User comments at the bottom are also great! They are usually insightful and have been very helpful in the past.
The writing for classes and extensions is also equally as good: well written, quick start guides, installation settings for Windows and Linux.
I've always felt that the website was very user friendly and accessible. When you go to the landing page you're not overwhelmed with information. Just a quick blurb about what PHP is, the news of releases, easy to find download options, and documentation and search are all above the fold and prominently featured.