Ask HN: What's the best documentation you've ever read? - selmat
======
manugarri
It has to be the scikit-learn documentation ([http://scikit-
learn.org/](http://scikit-learn.org/)). Not only its great in terms of proper
code documentations with a ton of examples, but it also explains the theory
behind each algorithm. You can literally learn Machine Learning just by
reading the docs

------
devxpy
Any discussion on documentation is incomplete without mentioning Django

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

~~~
danpalmer
Came here to say this.

The thing I love about Django’s documentation is the layering. From beginner
tutorial through to high level overviews of the subsystems, through to
detailed usage for the subsystems, through to API level docs, through to the
source code - all of it is there, and all linked together well. On top of
that, it’s all well written, approachable, full of notes and caveats/warnings
where necessary (for the level of the documentation too).

I’ve not seen another set of documentation that provides something at each of
those layers.

~~~
sametmax
The warning and caveat are the best part for me. The django team understands
very well the principle of least surprise, which is why old django installs
still work, the ecosystem is very well intagrated and updates are not dreaded.
It strikes menthat something new like react is in version 16 (and the doc
sucks) while django is much older and only reaching v2, with great docs.

~~~
spicyj
I work on React. We've worked really hard on our docs, so it would be helpful
to know what you don't like about them so we can improve.

~~~
danpalmer
I don't use React much, but from a quick look at your docs now it looks like
they are much better than last time I saw them, and I can't find any major
points of criticism.

I like the fact that you have the separation between getting
started/tutorials, main concepts, advanced concepts, and an API reference. The
notes/caveats/etc seem reasonable.

It would be nice to link to the source in the API reference, and there are a
lot of mentions of APIs that could be linked (pretty much any function name in
a body of text could be linked I think), but apart from that these docs look
great.

That said, I haven't had to use them day after day for 6 years like I have
with the Django documentation!

One thing you might want to consider for the future would be switching between
versions of React. Django has a version switcher at the bottom of the screen
that lets you jump between versions, shows banners when reading the docs for
unreleased/insecure/old versions (in case users are linked to them), and also
mentions when APIs were added in recent versions in the text.

~~~
spicyj
Thanks!

* Links to source: I use these frequently in other libraries, but I don't think this would be as useful for React, because we tend to have just a few functions each with a complicated implementation (vs programming stdlibs or other frameworks where many methods are on the order of 10-100 lines calling other public functions). Also our implementation isn't that easy to understand. I wonder if you had a particular use case in mind? * Linked method names: Good idea. * Version switcher: We've thought about this and will probably add it at some point.

~~~
danpalmer
Not wanting to open a can of worms, and I haven't read any of the React
source, but if the source isn't that useful I'd suggest the answer might be to
make the code easier to understand. Developers often need to dive into the
code they are using for more detailed analysis of undocumented edge cases,
tracking down bugs in their own code, etc, and having an understandable
framework or library is fairly critical for that.

Django does a lot of complex/clever stuff under the hood, but the source is
still readable, and in most cases fairly easy to understand.

This is just my 2 cents though.

~~~
spicyj
Yes, making the source easy to understand is definitely valuable (even if only
for our own team's understanding).

I believe Django's "functionality/(API surface)" quotient is still much lower
than React's, which means it's easier to make the source useful to a newcomer.

------
mabynogy
MDN because it's exhaustive [https://developer.mozilla.org/en-
US/](https://developer.mozilla.org/en-US/)

Jekyll because it's beautiful and the user can read all the pages at once with
the previous/next buttons (at the bottom)
[https://jekyllrb.com/docs/home/](https://jekyllrb.com/docs/home/)

Node.js because they propose a single page version and it makes search easier
[https://nodejs.org/dist/latest-v10.x/docs/api/all.html](https://nodejs.org/dist/latest-v10.x/docs/api/all.html)

~~~
cimmanom
MDN is spectacular.

------
altschuler
I learned a lot from the SQLite documentation. It's not only very thorough,
but it's full of insightful bits of information that is not strictly necessary
but which gives a deeper understanding of the engine.

It was also the first time I encountered the flow diagram type of syntax
explanation which I found to be a fantastic way to grasp the details of each
command. Eg
[https://sqlite.org/lang_createtable.html](https://sqlite.org/lang_createtable.html).

[https://sqlite.org/docs.html](https://sqlite.org/docs.html)

------
croo
ZeroMQ stands out for me.
[http://zguide.zeromq.org/page:all](http://zguide.zeromq.org/page:all)

~~~
Buttons840
Yeah. I'm pretty sure I'd benefit from reading those docs even if I never use
ZMQ.

------
throwmeaway1532
The best docs on the planet are now held by Mozilla on Javascript.

~~~
hakanito
Agreed. I’m referring to it as the Truth

------
deadcoder0904
Vue JS docs are the best. I don't think anything beats it :)

~~~
sametmax
I always feel like the author is my buddy talking to me. Sometime i have a
question, then read one. There is it, the answer.

And this applies to the vue API as well. The guy just crafted in so many
little things to make real life easiser. The event.once helper for example.
Simple, elegant, useful.

------
cellover
PostgreSQL's documentation to me is a reference.

Complex concepts are told in a very simple and concise fashion. There is just
the right amount of text for what is told, it does not make you feel dumb and
instead invites you to dig deeper in a very welcoming manner.

~~~
mmt
I even suggest it as a good way to learn about relational databases, in
general.

The only downside is if the reader is "spoiled" by a particular feature that's
documented as standard (such as to comply with one) and subsequently has to
work with one that lacks it or implements it less completely.

------
federicodalmaso
CockroachDB:
[https://www.cockroachlabs.com/docs/stable/architecture/overv...](https://www.cockroachlabs.com/docs/stable/architecture/overview.html)

------
minikomi
Re-frame for clojurescript. Worth reading even if you're not using cljs but
are involved in front-end development.

[https://github.com/Day8/re-
frame/blob/master/docs/README.md](https://github.com/Day8/re-
frame/blob/master/docs/README.md)

------
mjw1007
The TeXbook, and the Exim spec.

The thing the latter gets right is that, as well as the usual long list of
options with an explanation of what their effects are, it also describes in
full detail what the program actually does, rather than leaving you to deduce
it from the options.

So each option is normally described twice: once in an alphabetical list, and
once where the operation it affects is described.

~~~
pasbesoin
I remember the TeXbook, from back when it came out (more or less). One of
those books that tells you what's going on, provides a very good summary of
its context, and makes you want to read it.

More documentation back then seemed to be of higher caliber, than much if not
most of what we wade through, today.

I think the people writing it had more time and resources for attention to
detail. And perhaps more need. There was no generally public Internet for
updates and corrections including turning your product from a pain in the ass
quasi-brick to something useful. You had to get it right, up front.

------
jolmg
vim, emacs, postgres, zsh, bash, urxvt, systemd, pacman

EDIT: It all depends on how you set the bar, though. There are plenty of
projects whose entire documentation is a README with a few examples.

Also, what's "best", documentation that greatly explains a horrible,
unintuitive interface of a program or one that hardly needs to exist because
the use of the program is so intuitive, you don't need documentation? Greater
effort was spent in the former, but you understand the program better in the
latter.

------
snicky
I love [https://redis.io/documentation](https://redis.io/documentation). It
has a great UI too.

~~~
sametmax
It scaled well too. Redis was a small tool. It's not so small anymore, but the
doc is still top notch.

------
incadenza
Redux is good given how small the library is. Rust stands out as well

~~~
mjw1007
I'm underwhelmed by the Rust docs.

The tutorial is OK-ish, but the reference docs are weak. If I have a specific
question about some detail of the language, the answer is very rarely there.

Sometimes the answer is written up in the bug-tracking system or an RFC. They
don't seem to have a culture where someone making a behaviour change, or a
language-definition decision, is expected to update the reference manual at
the same time.

~~~
steveklabnik
Please file bugs against the reference when you have these kinds of questions,
it really helps.

> they don’t seem to have a culture

We actually do have that as a literal rule [1], but since we’ve started from a
place where the reference is incomplete, we can’t block everything on fully
filling out every last detail. It’s being actively worked on though!

1: the rule has been slightly relaxed in the last few months for reasons; now
a bug must be filed, rather than writing out the literal text. They usually
get done fairy shortly after though.

------
stevesimmons
Django, the Python-based web framework, has fantastic docs too:
[https://docs.djangoproject.com](https://docs.djangoproject.com)

~~~
collyw
Pythons standard docs are pretty disappointing in comparison. It takes a lot
of reading to encounter what you need.

~~~
sametmax
And don't get me started on the stdlib doc part dedicated on asyncio.

------
rmrfrmrf
_The C Programming Language_

------
programmarchy
The node-postgres docs are very nice. [https://node-
postgres.com/](https://node-postgres.com/)

Gives you examples right off the bat to get started, is organized well so it's
easy to dive deeper, and the author includes some conventions for
incorporating the module into your app.

------
leni536
I think cppreference.com is very well made. It has both the C++ and C
standards in a very accessible form.

------
HappyFapMachine
QT wasn't so bad as far as I remember.

But as jolmg pointed out, some projects are just simple readme and that is
more than enough. Love those. But the total opposite is also common, a wall of
text that is meaningless and in the end, you have to go through the source
code to get some answers...

~~~
slavik81
Qt had amazing documentation around Qt 4.5. It's still really well-
written—especially the old stuff—but their biggest problem is that they're
awful at maintaining websites. The expected lifespan of a link to a page in
their documentation is about two years.

------
wizawu
Erlang - [https://www.erlang.org/docs](https://www.erlang.org/docs)

The best three entries are * Learn -
[http://erlang.org/doc/reference_manual/users_guide.html](http://erlang.org/doc/reference_manual/users_guide.html)
* Use - [http://erlang.org/doc/search/](http://erlang.org/doc/search/) * Go
deep -
[http://erlang.org/doc/efficiency_guide/users_guide.html](http://erlang.org/doc/efficiency_guide/users_guide.html)

------
neddeadstark
I would go with python-requests [http://docs.python-
requests.org/en/master/](http://docs.python-requests.org/en/master/)

------
actionowl
[https://docs.saltstack.com/en/latest/topics/development/inde...](https://docs.saltstack.com/en/latest/topics/development/index.html)

I found some bugs and I wanted to fix them. I've done a little python in the
past but I'm not entirely up to speed on the whole python ecosystem. This
documentation was exceptional and allowed me to get my bugs fixed, some unit
tests written and PR's merged.

------
sbergjohansen
I've always admired Agilent's Programmer's Reference for the ESA series
electronic spectrum analyzers
[http://literature.cdn.keysight.com/litweb/pdf/E4401-90507.pd...](http://literature.cdn.keysight.com/litweb/pdf/E4401-90507.pdf)

------
haolez
Racket

[https://docs.racket-lang.org/](https://docs.racket-lang.org/)

~~~
soegaard
Note that all identifiers in the code examples are links to documentation.

------
amarant
I really like the elasticsearch docs. They seem to cover everything, it's easy
to find what you're looking for, and they contain a lot of detail! the feature
where you can switch ES version without leaving the page you're on is a nice
touch too :)

------
beizhia
It's gotta be emacs for me. C-h o, and helm-apropos make it super easy to
investigate anything in the system. And the help pages link back to the source
code (though this isn't unique to emacs) The online docs aren't bad either.

------
yantrams
MDN, Scikit-learn, Requests, RethinkDB, Django are a few that come to my mind.

------
random42_
Probably the Gentoo Linux documentation. Not sure how it looks like today, but
back in 2005 when I started using Gentoo it helped me a lot because not only
was comprehensive but also deep enough albeit clear.

------
saluki
Best docs:

Stripe.com

Laravel.com

~~~
gremlinsinc
Laravel by far my favorite framework, but their docs aren't perfect, there's a
lot of things I've needed to do, that just aren't in the docs, they're in the
API though.

Everything in the api, should be covered somewhere in the docs with examples
and use cases, imho.

------
tephra
I really like the Org mode manual
([https://orgmode.org/manual/](https://orgmode.org/manual/))

------
rkachowski
nobody know shoes by _why

I would say it's pretty terrible at providing a reference for a new GUI system
in ruby, but it's also the most fun I've had reading docs

------
klausjensen
Stripe has the best API documentation, I have seen.

~~~
danpalmer
I used to think this, but from a recent project with them we found them to be
lacking some significant details, and generally fairly shallow. We had to
contact support for a lot of clarification, and that took a while with the
back and forth.

------
kaycebasques
Tech writer here. I'd be hugely thankful if you included _why_ a given set is
the best in your experience!

~~~
WalterGR
(Off-topic: I'm considering a career change from software engineering to tech
writing. I'd love to pick your brain about the field. There's no contact info
in your profile, but I'm waltergr@gmail.com. Thanks for the consideration.)

~~~
kaycebasques
Just saw this. Absolutely. I'll email you.

My personal is kayce@basqu.es for anyone else in the same boat.

------
nortiero
The Commodore 64 User Manual. No contest.

------
jackgolding
I like plot.ly's documentation - has a good mix of top level examples and
specific, deep documentation.

------
tcpekin
I use Matlab over Python for scientific computing mainly because the
documentation makes everything easier.

------
billconan
Qt's [http://doc.qt.io/](http://doc.qt.io/)

------
rajangdavis
IMHO Twilio's documentation is pretty nice

------
bobosha
stripe - hast the best api docs imho

------
akskos
Go

~~~
Numberwang
Really? I thought they were horrible. I gave up on learning the language
mainly because of the documentation.

~~~
ioddly
I've never tried to read the Go documentation from the top down, but godoc is
pretty excellent.

------
Walkman
PostgreSQL's is very concise, clear, to the point, but still very detailed.
Has examples!
[https://www.postgresql.org/docs/10/static/index.html](https://www.postgresql.org/docs/10/static/index.html)

------
Theodores
Stack Overflow.

