Ask HN: What is the best product documentation you’ve ever seen?
What makes you go “wow” at documentation?
I’m looking for some inspiration on technical product documentation in the DevTools space (think cloud platforms, CI/CD, etc.) Personally I think MDN is one of the best examples of a really good docs site:
https://developer.mozilla.org/ Not DevTools but Matlab's product documentation is superb. I've learned a lot of signal processing, image processing, communications theory, statistics, and more just from the docs and examples (code, LiveScripts, and Simulink models). Very well written and easy to access from command line, editor, and/or the web. I would have to say that the best technical documentation I've ever come across has to be the Commodore User Manuals for VIC-20 and Commodore 64. Coupled with Compute!'s Gazette I was able to launch a career in BASIC programming. The user manuals completely documented the entire architecture of the KERNAL and BASIC system, as much as any programmer could need to do all sorts of things. Kudos to Commodore on documentation, definitely a lost art, and never found in Windows-based apps again. Similarly, the manual that came with the original ZX Spectrum rubber key version was awesome, with a complete description of Sinclair BASIC and all the Z80 assembler op codes for good luck. The 48k+ manual that followed was nowhere near as useful. Reminded me of having had a printout of the disassembled ROM at that time. Airship, formerly Urban Airship, i think. a few years ago i was helped to build out a Sphinx-based search feature, integrate it into a Pyramid-based app, and something UA were doing made me want my app/docs to look/act like theirs part of it was the search, part of it was the comprehensiveness, part of it was the magically-appearing in-page #anchor links when you'd mouseover an <H>-type header element so that you could easily refer to a section of a page -- something which i feel like is obviously crucial to useable docs, but rarely exists in real life, and part aeshetics. a quick glance just now seems they still have docs, tho i guess most established company doc sites would look good and generally be high-functioning these days. i suspect more of them were built from scratch back in the day, but not sure -- it's prob difficult for the docs vendors to keep up with integrating api tools, etc. I bought a Fluke 8840A bench multimeter recently. Its manual has comprehensive electrical schematics of the internals! Not only that, a significant portion of the manual is taken up by explaining exactly how each portion of the circuit works. Mine didn't come with the AC option, but if I wanted to I could build one without having to reverse engineer the schematic. As someone who didn't grow up in that era (was born in the late nineties) that's pretty wild to me. In that domain, also, the Swanson speed square. Comes with a 'blue book' full of all kinds of tips and tricks and measurements. The elixir docs. Much is generated from the code itself (the language "requires" it, so up to date), with very nice interlinking to functions etc. I might be stretching the terminology here as far as "technical product documentation" but Arch Wiki has been an absolute blast for me as a source of not only specific distro knowledge but general Linux information. Very concise a yet somehow also very comprehensive. Hardware Design with RP2040 [0]. An official guide on integrating the Raspberry Pi RP2040 microcontroller into one’s own circuit design. Essentially a series of worked examples that touch on pretty much every hardware feature of the chip, with a good amount of advice transferable to other microcontrollers. Provides steps and justifications. The RP2040 datasheet is equally fantastic: straightforward wording, minimum abuse of passive voice commonly seen in microcontroller literature, and accompanying C/asm examples. [0]: https://datasheets.raspberrypi.com/rp2040/hardware-design-wi... Visual Studio App Center has excellent documentation: https://learn.microsoft.com/en-us/appcenter/distribution/cod.... It's comprehensive and well structured. If you're looking for a system that looks as good, mkdocs (https://www.mkdocs.org/) with the mkdocs-material theme (https://squidfunk.github.io/mkdocs-material/) can get you quite close! I’ve always found the msdn documentation to be excellent. Although sometimes finding stuff can be overwhelming. DEC's documentation for VAX/VMS and related apps. The great orange/gray wall of heavy-duty binders. What wowed me: whatever I needed to know, it was in there, I could find it, and the software behaved as the documentation said. Although I have not read DEC's (Digital Equipment Corporation) documentation, but I've come across a 1990 book that mentions DEC's approach to documentation: > Digital Equipment Corporation noted in their 1983 internal documentation guidelines that user documentation should be written first — not last as is traditionally done — because the user documentation is an excellent way to debug the design of a system or a program. “If a writer finds it difficult to document a system, the problem is probably the system not the writer. Holes in design, obscure constructions, and apparent contradictions become starkly visible in the documentation.” (From book: Writing better computer user documentation, 1990) The FastAPI docs are fantastic: https://fastapi.tiangolo.com/ I'd rather have more concrete documentation of the API, the current version is structure more like a long tutorial. I like semi-automatically generated docs like AWS API docs that contains in minimum the type information for every field there is, and often much more. I don't like Python docs where it ends up on long winded explanation for specific cases but does not cover all arguments, or only mention some in passing. I am the exact opposite. I dislike semi automatic docs like most rust libraries have that don't tell you anything about how you're supposed to use things, and I love the general python docs that are the opposite. Django in particular is super good at this. I would compare it to having a recipe vs a list of ingredients. Both are useful but I can't just cook if you just give me a list of ingredients without instructions. And then you have NestJS that does neither so you just get a random piece of information but missing 75% of instructions and no good API doc. Microsoft SCCM uses SQLserver under the hood and the developers created a lot of database views to access information. The documentation about how to construct queries using those views was excellent, including good use of color coding. Nicely done approach to de-complexifying a fairly complex schema. I am unlikely to use a product if I cannot figure out how to use it intuitively. I prefer products that are easy to learn and use, without the need for extensive documentation. Surprised to see Postgres documentation not being mentioned. It is one of the most comprehensive and intuitive documentation I have ever seen https://docs.posit.co/, it just makes sense the way everything is organized. Prisma's docs[0] are one of the best I've read I remember fondly a wall of Sun/Solaris manuals in binder form. Was a great introduction to all things Unix. You may find it surprising, but Vim. Borland Pascal and Borland C 3 help. Hot take: Apple’s. The parts of their SDKs that are documented follow the same pattern of giving a broad overview of what a type is and what it can do, and then the declarations are grouped by topic so that you can jump straight to the part that you need instead of scrolling through the whole thing just to find only the one thing that you intend to use. Algolia’s did a great job of getting to wow quickly by walking me through setting up an index SQLlite, no question. Hmmm, not really. There's a bunch of stuff there, but sometimes it's missing needed info. Wish I could think of an example off the top of my head though, but nothing is springing to mind. Was doing stuff with (the official) SQLite extensions a few weeks ago, and the docs didn't really cover some of the things I was after at the time. Not the end of the world, just a bit frustrating. Stripe Is it really that good? Every time I want to document my own APIs I give a look at Stripe’s docs because everyone praise them, but I always end up unimpressed. Their docs don’t feel that good to me, not very readable or particularly clear. Am I missing something? Having implemented subscriptions and using the docs, it was ambitious, confusing and hard to know what parts were applicable or not. What I needed from the docs was a good tutorial. Yeah, same here. I've been finding them confusing, with seemingly conflicting information. Asking for assistance and giving feedback just gets completely ignored now, whereas when we first created our account the support staff were very keen + helpful. Not sure what's changed, but it's not good now. :( Ironport manual Django Definitely - CloudFlare! I'd say Cloudflare has good documentation, but would be beaten by the likes of HashiCorp. Cloudflare can bounce you around a lot in their documentation. Jumping from their base docs, to GitHub to Docker Hub. In some cases I've found conflicting versioning / information between those sites. Don't get me wrong, Cloudflare does a nice job. So many vendors today don't have a documentation forward perspective. I recently worked at a startup that had basically no documentation and found that the product was poorly designed and did not work as they advertised it. At this point in my career one of the first things I'm looking for when considering a product or organization is good documentation. Skipping that validation has almost always bitten me. A lack thereof seems to indicate taking a shortcut and broader issues that may be lurking.