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!
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.
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...".
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.
There are great examples of top-down authored docs in this thread, but Arch's docs manage to be comprehensive while being largely community contributed. Odds are if I have a question about any Linux distribution, I can find an answer for it in Arch's docs. As a result, they also often have considerable localization.
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.
Wow! The last 4 would have been my entire list. I'm unfamiliar with the first four, but given the end of your list, I have to imagine we have really similar opinions about documentation. I'll definitely keep that git book in mind should I ever want to learn more about git.
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
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).
An interesting perspective is most of the suggested docs were written in the last couple years, at most.
I think you'd benefit by finding retrocomputer people and asking them about docs they've seen to find the best technical writing of the century.
I don't have a short list of IBM Mainframe docs, but those are probably "the best documentation money could create" in the 50s-70s.
Easily second best would be the DEC TOPS-10 Software Notebook Series which in my experience was a set of 20 binders and in one shelf it contained all you need to run a major 80s minicomputer operating system including apps.
What 80s DEC documentation did VERY well, was every doc was planned out intelligently and in detail by actual users to make sense to a professional sysadmin on the job. Unlike "sales/marketing" driven docs, the software notebook series TRULY understood its audience of professional sysadmins. I also feel that 80s DEC documentation had the best intros in technical writing I've ever seen. Intros are underrated and the author(s) need to make a "contract" with their reader before throwing detail at them. Take for example, volume 6 or so of the dec-10 software notebook series which has the ALGOL programmers's reference guide with the best intro ever. "This is where you start" should be the most carefully designed and written chapter of the docs, not a filler chapter. In summary, don't skimp on outline and don't skimp on writing a real intro.
Personally I like some of the Tandy/Radio Shack Z-80 manuals. Perhaps the extended basic manual for the model III, or the 6809 assembly book they resold are the pinnacle of late last century technical writing for a more general audience.
Retrocomputing is a fun hobby that extends far beyond technical writing critique, obviously.
I agree with you, but let's be honest, if you aren't already well exposed to that world then those docs are going to scare the shit out of you. They definitely are not "easy reads". The extent to which you are looking for something reference like and intensely technical vs. something to ease you into a new stack will determine whether you appreciate IBMs mainframe docs. They definitely don't fit the mold of what most people expect from documentation nowadays though.
If anybody wants to see what they look like, type IBM zOS v2r5 indexed collection into Google (the most recent batch of docs). I don't really have any one in particular that I would recommend starting with, because none of it is going to make much sense if you are new to that world.
The ABCs of Systems Programming Redbooks are probably a better introduction than the main documentation, although those volumes are a little bit more out of date.
They came in binders because, regularly, you’d receive a packet of new pages, sometimes a few, sometimes tens or even hundreds, with instructions on where to insert them in the binders and what pages to discard.
I agree with this. The Postgresql docs are adequate--not outstanding, just adequate--by the standards of the mainframe and minicomputer manuals of those days. Nothing else today even comes close[1]. There are so many things you just have to try.
1. OpenBSD makes a good attempt, but the project is under-resourced.
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.
Vim hasn't been mentioned. It's right in the program. It's got a tutorial, a userguide, a reference manual. Stuff is hyperlinked. Follow link with Ctrl-] or double-click, go back with Ctrl-t. You can seek help on specific things like options (:h 'ai'), commands (:h :s), normal mode commands (:h w), insert mode keybindings (:h i_ctrl-r), command mode keybindings (:h c_ctrl-f), vimscript functions (:h getline()), etc.
The text itself is also well written. It's clear and doesn't feel lacking in detail.
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.
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.
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.
I have mixed feelings about Perl. The documentation tends to be in a style that prevents quickly scanning it. Instead you have to read dense text to make sense of things. For example: https://perldoc.perl.org/IPC::Open3
If you want to quickly figure out what the parameters for open3 are doing, you are forced to read through the description. It reads like a casual conversation someone is having with you, lecturing you about the function, dropping some important information here and there without any clear direction.
I like GNU documentation (texinfo): reading those both as info manuals (usually in Emacs) and as HTML (in a web browser). Nice search and convenient navigation in an info viewer, available (and convenient) both offline and online, hyperlinks, HTML versions don't rely on JS (and do try to stay compatible with ancient web browsers), and it's rather generic (not language-specific).
Edit: I think pretty much all the GNU documentation (and most of texinfo documentation) I saw was nice, but as particular and common examples, there are manuals for Emacs and Elisp, GNU libc, coreutils, bash.
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).
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.
Kubernetes for sure. When anyone asks for a good place to get started with understanding k8s - I tell them the docs should be all you need, then go get hands on.
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.
I often found the React documentation helpful. React can be different things to different people, so I guess it's ok for the "primary" documentation to focus on reference and guiding principles and leave the more practical guidance to secondary venues.
You won't find many common threads there. No tool (yet) designs an effective information architecture, consistent style, audience awareness, or comprehensive topic coverage. Those all have to come from the contributors.
Aside from providing a front end for viewing and maybe editing, docs publishing tools mostly help make that content more accessible, provide some search and versioning functionality, ease some maintenance tasks, provide static publishing options like PDFs, and handle asset management. Maybe you get luxurious and have an authoring/reviewing/publishing workflow from a headless CMS, but most shops these days just try to bend a software issue-tracking system into doing that.
It provides multiple layers of documentation along multiple dimensions.
Say you're an end-user. Where do you start? Maybe you read the tour on the webpage. Maybe you watch one of the countless videos. The first time you open Emacs, your cursor is on a link to the tutorial. The tutorial is interactive and allows you to save and continue later. The system sets you up for success in learning.
The tutorial leads you to the manual, written in Texinfo which is published in multiple formats. Within Emacs, you can use the info browser (you can access the same from the terminal outside of Emacs) to search and navigate the documentation. All manuals and references are also published to Html (as single page to facilitate searching terms across sections), as well as PDF and bound paper copies (available from the FSF). There is no single interface to the documentation. The interface can be a web browser, the info browser, your thumb on a physical page, etc.
Info/texinfo is amazing. Documentation is indexed. This allows you to search for terms, as well as section headers and keywords. If a term doesn't appear explicitly within the text or within your current document, it may be included as an index. What would fail in the pdf or html is found this way. You can search across documents (for example, the user manual vs. the programming reference). The apropos function even compiles search results as a table of contents.
Navigation of the documentation is robust. Forward, backward, up, down, top. Within Emacs, this is even better. There are lookups for functions, variables, and symbols. Lookups within the various documents (manual, reference, do strings, etc) is quick and integrated. Because the cost/pain of lookup is low, as well as terms indexed, separate documents feel like one.
Each function and variable has a quick-to-access docstring. The docstring may include links to other useful features or reference to other documentation. Documentation always has a link to the source code.
A lot of what I've said addresses the interface to the documentation. It's also important to consider the use-cases for the documentation and its intended audience. There are tutorials to introduce high level concepts (assuming zero prior knowledge), there are references for in-depth explanation of component details, there are docstrings to explain specific functionality, and there is the source code, two clicks away and able to modified immediately. When pictures are helpful, they're there. Manuals include examples, offset from the main text.
There are clear, published guidelines for how to write documentation. I've found those generally helpful.
There are mailing lists which are excellent documentation. The rules for participating, such as avoiding top posting and organizing topics in threads, aid comprehension and accessibility. The mailing list documents why decisions are made. They document the history of an idea.
If you've ever wondered why some people are fanatical about Emacs, an underlying reason is that information about it is really easy to get at and is accessible.
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.