HN Explorer

Ask HN: Which are your favorite developer docs?

35 points by lucasjanon ↗ HN
I'm currently working on documenting a product for developers, I'm used to read lots of public dev docs, but it's my first time writing them.

I'd like to get some inspiration, could be favorite developer docs, but also resources on how to make them great.

Examples:

Stripe (https://stripe.com/docs): probably the canonical example for dev docs, well written, well structured, sweet spot between code examples and explanatory text (e.g. https://stripe.com/docs/billing/quickstart).

Tailscale (https://tailscale.com/kb/): well written, well structured, lots of how-to guides.

Docusaurus showcase (https://docusaurus.io/showcase): aggregation of docs, some of them are great, some are not. All of them are open source so it's a useful resource for inspiration.

Also, not a doc itself but a great tool to build docs: https://codehike.org/

23 comments

[ 3.4 ms ] story [ 53.3 ms ] thread
kosasbest
Invaluable:

https://devdocs.io/

https://developer.mozilla.org/en-US/

Grimburger
I have used devdocs with no internet access on planes for years now.

Whoever runs it deserves some sort of medal. Such a valuable resource.

lucasjanon
devdocs is great, didn't know it, thanks!
LanternLight83
This is a really awesome project, and I really appreciate how pleasant the interface is. Wonder what it would take to parse in existing man files? It works great for all those front-end frameworks, but Linux Man Pages /are/ the most voted request, and several other suggestions provide standard formats.

Comment on the Linux Man Page request frequently focus on where to get HTML versions, or where to source the files from.

I think the answer is to parse the man pages into HTML (maybe with Pandoc) with the existing CSS/JS, not scrape existing man page web front-ends (of which this would qualify). A swath of docs could be imported by creating such an importer and collecting the "doc" outputs from functional package repositories like Guix and Nix, which tend to stick very closely to upstream; any modifications are rare, explicit, and easily removed.

quantumwoke
Is it just me or are the Stripe docs not the paragon of usefulness they once were? Still head and shoulders above many but last time I started a new project I found duplicated, outdated, confusing docs all over the place. Managing the complex payments state machine seems to get harder and harder as Stripe matures.
raphaelj
I had the same impression the last time I had to look at them.

Basic payment processing feature are still well documented, but once you get into their Connect or subscription stuff, it gets a little messy.

wswope
I dove in for the first time several months ago and had the exact same impression. I found the data model and webhook system to be pretty quirky on the whole - though not impossible to work with at all.
[deleted]
(comment deleted)
jpgvm
PostgreSQL is the gold standard for usage level docs.

The Linux kernel however is by far my favourite because of the in-depth design documents in-tree in easy to read plain-text format.

giraffe_lady
I like the postgres docs as much as anyone but those flow diagrams sqlite has for commands are incredible and I wish pg had something like them. I know postgres tends to have way more options and they'd be unwieldy in some cases but still valuable I think.
jpgvm
Yeah those are nice. sqlite also has great internal design docs too, on par with the kernel. Surprised it slipped my mind actually as it's one of the best maintained and documented projects full stop.
Maultasche
I really like the Elixir programming language documentation: https://hexdocs.pm/elixir/Kernel.html

It's easy to find things, clearly written, and usually answer any questions I have about how to use a particular standard library function.

I really appreciate the code samples, which are present all over the documentation.

grossvogel
My favorite feature is the way source code links are added automatically and consistently. Just look for the little </> links to the right of the module / function / macro name!
alexdowad
MDN for the JavaScript language and standard browser APIs.
dontbenebby
Do man pages count? (I'm not trolling... I often pull them up on the web rather than in terminal but they're incredibly useful.)
pull_my_finger
The Lua language documentation[1] covers the entire API with examples and signatures, the language grammar and the changes from the previous version including specific incompatibilities where applicable, all in a single page. It's all very easy to read and understand.

[1]: https://www.lua.org/manual/5.4/manual.html

dehugger
I love the flask documentation personally. I've always found it well laid out, with relevant examples for my use cases. Also EVE has the best video game rest api and documentation I've ever used.