Ask HN: What are good examples of technical docs you've seen? Bad examples?

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.

Bad : mongoose.

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.

Qt's document is among the best: http://doc.qt.io/qt-5/index.html

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.

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.

New York Times API docs

Django's docs are some of the best I've seen

https://docs.djangoproject.com/en/1.10/

I love how they provide example code for everything and explain it.

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.

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?

I love how MDN (Mozilla Developer Network) documents web APIs.

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.