HN Explorer

Ask HN: What is the best product documentation you’ve ever seen?

45 points by half0wl ↗ HN
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.)

42 comments

[ 0.23 ms ] story [ 38.1 ms ] thread
NoZebra120vClip
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.
mharig
Reminded me of having had a printout of the disassembled ROM at that time.
pechay
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.
mobilio
Definitely - CloudFlare!
windexh8er
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.

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

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

eitally
SQLlite, no question.
justinclift
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.

foreigner
Stripe
thiht
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?

martin-adams
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.
justinclift
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. :(

OldGuyInTheClub
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.
[deleted]
(comment deleted)
YVoyiatzis
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.
tomkarho
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.
prxtl
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!

nirav72
I’ve always found the msdn documentation to be excellent. Although sometimes finding stuff can be overwhelming.
satiric
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.
silisili
In that domain, also, the Swanson speed square. Comes with a 'blue book' full of all kinds of tips and tricks and measurements.
hulitu
Borland Pascal and Borland C 3 help.
mmikeff
Algolia’s did a great job of getting to wow quickly by walking me through setting up an index
rTX5CMRXIfFG
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.
rochak
You may find it surprising, but Vim.
xyx0826
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...

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