HN Explorer

Ask HN: Best examples of software documentation that you've come across?

103 points by nickgut0711 ↗ HN
Hi all. I'm currently trying to revamp the software documentation of a library that I'm trying to build. I would like to see examples of documentation that allows you to easily find the information you need. Thanks!

99 comments

[ 3.2 ms ] story [ 192 ms ] thread
MaxPengwing
Microsoft Developer documentation is imho best in class. https://learn.microsoft.com/en-us/docs/

Point in case https://learn.microsoft.com/en-us/dotnet/api/system.linq.enu...

zdimension
Unfortunately the quality of the docs varies a lot. Most COM APIs are empty (i.e. their doc page contain only the functions signatures, with no description or explanation), while .NET is really well documented
MaxPengwing
true, but when they are good, they are some of the best I have seen.
mauvehaus
Postgresql, hands down. https://www.postgresql.org/docs/

And they do a great job of keeping docs for older versions available. They're on version 15 and they have back to 7.2 available.

If I can't figure out how something works in another DBMS, I usually read the comparable postgresql docs to get a good overview, and then go and re-read the docs for what I'm actually using to fill in the implementation-specific bits.

joshxyz
These are god tier docs.

When using mysql i search for postgresql docs, because mysql docs sucks, good thing they implement same sql standard on most parts.

jedberg
The Stripe docs are the gold standard on API documentation:

https://stripe.com/docs/api

jameshiew
I would second this. Having interactive examples alongside the documentation (in multiple languages nonetheless) was something that stood out to me the first time I had to read the Stripe docs some years ago.
mothcamp
Slack: https://api.slack.com/docs

In addition to being thorough, it has personality.

joshcanhelp
I’ll second this one. They don’t try to be cute or too funny, it’s just written in a casual tone. My only (fairly minor) problem is that it’s not always clear where to start. Once I’m in the right general place, I’m pulled along really well but, because there is so much that’s possible, it feels like they need a better overall getting started place.

Still, grade A work over there on docs!

noman-land
Literally came here to say this. Great docs.
eatonphil
An indirect answer, here are the components of good docs I think about:

1. Reference docs that describe the behavior of the thing and the API

2. Example code and tutorials that show you how to use the thing

3. Architecture docs that describe how the thing works at a high level and how you integrate it into your system

4. Operational docs to tell you how to run the thing in production with backups, monitoring, debugging, and scaling

5. FAQ and anything else

Lots of docs tend to focus on only a few of these. But you've got really great docs when you bring these all together.

milliams
While it's not an example of documentation per se (though it does follow its own recommendations), I'd highly suggest looking at Diátaxis (https://diataxis.fr/). It gives you a logical framework for organising your documentation in terms of the use cases.
pletnes
FastAPI! It shows the thinking and development process with diffs, going through each task.

(There are other projects with better «reference style» docs)

stuckinhell
MongoDB. I'm not a fan or user of MongoDB, but their documentation is just stellar.
vanilla_nut
They have a damn good documentation group, largely because they hire a lot of engineers and teach them the writing bits on the job. I find documentation quality is often directly correlated to the technical understanding of the writer. To write good docs, you need to understand how to write well, of course. But you also have to beta test a lot of (undocumented!) features and become an expert in extracting information from code and engineers.

The beta testing and information extraction parts of that are damn near impossible without engineering experience.

hangonhn
https://redis.io/commands/

Redis command docs are excellent and you can try the commands on the site itself!

Also love that they include the availability by version and the time complexity and tag the commands such as @slow for potentially slow commands, etc.

elteto
Also, the redis source itself. You know when they say “the code should be its own documentation”? Redis is a prime example of that (plus it has many good actual comments too).
quectophoton
And not only that, you also can just run:

    git clone ${REPO_URL} redis && cd redis && make
... and it will just work. Few projects are that pleasant to build.
yboris
Interesting idea: Four Quadrants of Documentation

https://documentation.divio.com/

The idea is that there are four different goals that should be accomplished independently.

tonyhb
More directly from https://diataxis.fr/. The person who came up with this worked at Divio; Diataxis is the canonical name for this framework!
mcdonje
I haven't seen this before, but it rings true. Nice conceptual framework.
jslakro
What a great resource and concept. Thanks for sharing
helsontaveras18
Marqeta’s documentation is really good for describing highly complex payment topics.

Additionally the way they structured their API responses is brilliant. The API response data structures are deeply nested which means you have to perform less API calls to get related data (which often occurs with payments data).

https://www.marqeta.com/docs/developer-guides

blt
Matlab has great docs. Lots of examples and just the right amount of detail.

As an example, here's the doc for the backslash operator that solves a linear system: https://www.mathworks.com/help/matlab/ref/mldivide.html

nlowell
Matlab's focus on examples really shines. It's how people actually want to use docs: let me copy and paste something that works and then iterate from there.
makapuf
I'd cite the Django python web framework as one of the best documented projects I came across (and one the the reasons of its success):

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

someotherperson
Was about to post this myself. Django's documentation is fantastic, is strongly inter-linked and references other parts of the documentation throughout helping to build a stronger overall understanding. It also has all sorts of tips and tricks throughout which are almost always helpful.
bayesian_horse
Me too. I am currently forced (or at least heavily encouraged) to use ASP.NET, and while you could say its documentation is even more detailed, certainly not less, it lacks the clarity and "getting-shit-doneness" (TM). Somehow I find it harder to find what I'm looking for. And a few times I've been asking on discord channels and people wouldn't know either or only with asking multiple times like "come on, there has to be an easier way...". I didn't want to say "I know because Django has an easier way...".
HaveAGoodDay098
Easily MATLAB. MathWorks has a very dedicated and talented technical writing team.
tra3
Emacs has amazing documentation.

You can ask what a specific shortcut key does, you can ask what a specific lisp function does. Everything is linked together (so you can get from the shortcut to the function and vice versa) -- there's a direct link into code/implementation so you can traverse various levels of abstractions.

When I contributed a module to melpa last year, the biggest back and forth was about documentation and description of what everything does.

The doc system makes Emacs a joy to use and really makes it a stand out.

GrumpySloth
The Emacs info manual is also a gem. And the Emacs info mode is my favourite document viewer, which makes for a nice experience all around.
lucidguppy
Its not docs - but the "Awk programming lanugage" book it hands down the best book on any language ever. EVER!!!!
davidktr
I'll nominate R because the documentation is baked into the language. In Python I always need to lookup docs on the web whereas in R I've got everything I need right in front of me.