
Ask HN: What are good examples of technical docs you've seen? Bad examples? - nemild
I&#x27;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&#x27;ll keep the request wide since I&#x27;m interested in different forms (API docs, lib docs, quick start guides, reference docs).
======
darrelld
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.

~~~
Spoom
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](http://php.net/explode) will go right to the
explode doc. This works for root functions as well as classes and most
keywords.

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

[https://docs.djangoproject.com/en/1.10/](https://docs.djangoproject.com/en/1.10/)

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

~~~
0x54MUR41
I second this.

------
samblr
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](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.

------
doug1001
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

------
billconan
Qt's document is among the best:
[http://doc.qt.io/qt-5/index.html](http://doc.qt.io/qt-5/index.html)

------
JoachimSchipper
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.

------
x1798DE
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.

~~~
nemild
I'm going to be putting one resource together in the next week- will ping you
with a draft when it's done. Is there an easy way to reach out to you?

It'd also be helpful to better understand what is missing in the resources
you've read.

You can email nemild at google's email service.

------
cdvonstinkpot
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.

------
nemild
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?

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

