Ask HN: What's the best documentation you've ever read?

https://news.ycombinator.com/item?id=17399340

by selmat • 8 years ago

70 75 8 years ago

news.ycombinator.com

jolmg• 8 years ago

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.

saluki• 8 years ago

Best docs:

Stripe.com

Laravel.com

gremlinsinc• 8 years ago

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.

rmrfrmrf• 8 years ago

The C Programming Language

incadenza• 8 years ago

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

throwmeaway15322• 8 years ago

I don't see how anyone could like Redux' library. It's up there with Webpack in "dancing around but not getting to the point".

If you want to do anything useful with Redux, the Redux docs are pretty terrible.

I hate any docs that are written in "step" form rather than "book/info" form.

I search for a specific thing I want to learn about and apparently it's skipped over because it's not "a commonly used thing".

mjw10072• 8 years ago

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• 8 years ago

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.

throwmeaway15322• 8 years ago

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

hakanito• 8 years ago

Agreed. I’m referring to it as the Truth

deadcoder0904• 8 years ago

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

superasn• 8 years ago

100% agree. They are the most comprehensive docs I've ever seen. So many examples, nice clean design and they cover edge cases too.

It's the only doc that generally comes before SO in finding solutions for me.

sametmax6• 8 years ago

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.

cimmanom2• 8 years ago

Vue's docs are well written, and more comprehensive than most, but I came across some major gaps during a recent learning project.

beizhia• 8 years ago

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.

croo• 8 years ago

ZeroMQ stands out for me. http://zguide.zeromq.org/page:all

Buttons840• 8 years ago

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

stevesimmons• 8 years ago

Django, the Python-based web framework, has fantastic docs too: https://docs.djangoproject.com

collyw• 8 years ago

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

sametmax6• 8 years ago

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

devxpy• 8 years ago

Any discussion on documentation is incomplete without mentioning Django

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

danpalmer4• 8 years ago

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.

sametmax6• 8 years ago

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.

sshine• 8 years ago

I sat down to learn Django many years ago and felt the same way:

While the learning curve seemed to go on and on, the documentation had a half-tutorial, half-specification answer for everything.

snicky• 8 years ago

I love https://redis.io/documentation. It has a great UI too.

sametmax6• 8 years ago

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

mjw10072• 8 years ago

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• 8 years ago

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.

HappyFapMachine• 8 years ago

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• 8 years ago

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.

klausjensen• 8 years ago

Stripe has the best API documentation, I have seen.

danpalmer4• 8 years ago

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.

jackgolding• 8 years ago

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

programmarchy• 8 years ago

The node-postgres docs are very nice. 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.

cellover• 8 years ago

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• 8 years ago

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.

manugarri• 8 years ago

It has to be the scikit-learn documentation (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

altschuler• 8 years ago

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/docs.html

rajangdavis• 8 years ago

IMHO Twilio's documentation is pretty nice

akskos2• 8 years ago

Numberwang• 8 years ago

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

ioddly• 8 years ago

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

akskos2• 8 years ago

Wow. We had totally different experience with it then. To me it has always been simple and straight forward. Also the go tour was great to get started with the language.

Theodores• 8 years ago

Stack Overflow.

amarant• 8 years ago

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 :)

minikomi• 8 years ago

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

tephra• 8 years ago

I really like the Org mode manual (https://orgmode.org/manual/)

Walkman• 8 years ago

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

federicodalmaso• 8 years ago

CockroachDB: https://www.cockroachlabs.com/docs/stable/architecture/overv...

rkachowski• 8 years ago

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

sbergjohansen• 8 years ago

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

leni536• 8 years ago

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

mabynogy• 8 years ago

MDN because it's exhaustive 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/

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

cimmanom2• 8 years ago

MDN is spectacular.

bobosha• 8 years ago

stripe - hast the best api docs imho

neddeadstark• 8 years ago

I would go with python-requests http://docs.python-requests.org/en/master/

random42_• 8 years ago

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.

yantrams• 8 years ago

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

billconan• 8 years ago

Qt's http://doc.qt.io/

nortiero• 8 years ago

The Commodore 64 User Manual. No contest.

tcpekin• 8 years ago

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

kaycebasques2• 8 years ago

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

WalterGR• 8 years ago

(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.)

kaycebasques2• 8 years ago

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

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

haolez• 8 years ago

Racket

https://docs.racket-lang.org/

soegaard• 8 years ago

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

actionowl• 8 years ago

https://docs.saltstack.com/en/latest/topics/development/inde...

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.

wizawu• 8 years ago

Erlang - https://www.erlang.org/docs

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

Ask HN: What's the best documentation you've ever read?

Related Stories