Tailwind. Since tailwind classes expand to css, they could've called it a day by just showing those expansions, but they went further and each class has it's own section and every variant comes with an explanation, often accompanied with illustrations even. Their designer roots show too, because the illustrations are tight. Honestly, one could potentially skip having to refer to css docs and make do with just tailwind's.
Maybe it’s just me being stupid, but cppreference, while absolutely of great quality, some c++ pages can be as cryptic as it gets. I know, the language is very much not trivial due to all these features, but for example the page about the different kind of l/rvalues is very very complex.
I'm extremely fond of the official Elixir documentation - it's easy to read, has a standard structure, and most importantly (to me) you can click the "code symbol" (</>) to go to the actual implementation of the function documented.
Those were the halcyon days of technical writing teams sitting alongside developers. Extremely rare to see that now, and the organizational sclerosis from it is obvious from the vantage point where I sit.
You can immediately tell the really good technical documentation written in that old school pattern by its usefulness when you don't know anything about the code being documented. Because the good technical editors bring to the table a discipline and enforcement of a judicious eye for perspective, constantly, maddeningly, repeatedly, asking ELI5 until the words coalesce into something I can appreciate as a newbie to its tech stack.
If you want to see the documentation rot really set into the commercial industry (the situation is better in the bigger open source projects), look for documentation between versions. A common commercial software dodge now is the documentation site has a way to switch between versions of the same topic, and the budget for technical writers being non-existent, someone makes the decision to "helpfully suggest" there isn't an "exact match" for the same topic in the other selected version, and would the user like to change to the homepage of the selected version?
Product owners have forgotten that well-edited and written documentation integrated into the support and development lifecycle is an enormously powerful vendor lock-in.
I suspect that the PHP documentation has been the most effective.
I know everyone likes hating on PHP, but the docs actually work very well.
Part of it is because the language is basically a big standard library of functions, and those are easy to document, but the integration of user comments into each page has also been extremely useful to me.
Inside Macintosh (Apple's original system docs) was very good. Apple's documentation has steadily degraded, since. The documentation for SwiftUI is basically worthless.
Agreed! I remember going from mainly writing PHP to Python many years ago and being specifically irked at how Python's core docs, unlike PHP's, didn't "clearly" (in my view) list arguments and, importantly, examples.
PHP's one-page-per-func just seemed like a better way of focussing on/laying out everything there was to know about one function. This page [0] looks like it hasn't changed much in the last 15 years and absolutely brings back memories.
I don't have a view on SDK documentation but the best API documentation I've read is the Win32 docs.
Why? They are comprehensive, detailed, consistent, systematically presented, clearly explained and professionally written. Microsoft documentation has sadly gone steeply downhill since.
I still use Win32.hlp for most of my reference needs.
Microsoft documentation has sadly gone steeply downhill since.
I heard they decided to get rid of most of their documentation writers, and instead rely on "the community" to do it for them. And this horrible migration to a new system, which was basically an act that only the team doing it seems to be proud of:
Way downhill. The MSDN circa 1996-2000 (if that's what it was called, I don't recall) was excellent. Their C/C++/Win32 documentation was clear, helpful, and concise.
Then with the advent of .Net (or, at least, around that time, say 2000+) things just ballooned and suddenly the MSDN became super difficult to navigate, almost overnight. Even today, there's a lot (a lot) there but it's nowhere near as useful as is used to be. The MSDN habit of providing a TOC to the left of any given article seems like it /should/ be useful, but instead it's been beaten to death. There must be a better way to navigate their documentation than that.
Also, surprisingly often links to other documentation are broken - that's not new, it's always been the case iirc, but it's much more prevalent these days.
And, some of their stuff has a lot of documentation, but it's just difficult to follow. I swear they're paying technical writers by the number of sections they can chop a give subject into. I was looking into Azure/Business Central documentation a while back and didn't find anything useful even though there's a ton of information there. I had ~10-15 tabs open all roughly referencing different pieces of what I thought I needed. Eventually, I stumbled across a dev blog, not MS, describing almost exactly what I needed, along with some crucial details that I never saw in Microsoft's documentation.
What year? I can remember around 1998? having difficulty with the foreign language IME and having to delve through the disks we got from MSDN or something?(I forgot the name) from our annual subscription to figure out the details of using it and finding out it was only documented with examples in a prior year we did not have and having to dig up the example files someone helpfully archived on their non Microsoft website (it was scrubbed from the Microsoft website for some reason). Then I noticed some other poor developer have the exact same issue (so it wasn't just me!) on usenet so I just emailed the files to him.
Nobody would call it an "SDK" but I find the Emacs/Elisp documentation to be excellent both on the docstring level and the manuals. It has been refined over several decades, it is thorough, well written and very easy to use from the comfort of Emacs itself.
Java docs are great because they document:
* technical details and algorithms used
* side effects
* runtime and memory usage
* inputs that result in undefined behavior
* causes of exceptions
* behavior when accessed concurrently
* thoroughly hyperlinked
It's been this way for decades and the presentstion has remained largely consistent the whole time.
Second this. The core SDK and many common libraries are very well served by javadoc. I believe this is a key aspect of the success of Java. Javadoc serves so well that it compels Java developers to use it and you can tell if you're dealing with 'good' work or not by the thoroughness of the javadoc work.
Spring has often frustrated me in this regard. Spring's website is thorough and nearly everything you might need can be found there with enough wading, but Spring's javadoc is often lacking. You frequently run into placeholder entries and some of the key Spring packages and classes lack sufficient overview javadoc. Spring's indifference to javadoc is deeply stupid. I can think of several cases where Spring users have written suboptimal programs where they fail to utilize the platform properly, and I'm certain this happens in-part because Spring's javadoc fails to guide them.
One case I ran into in the last little while is a system that implements a configuration file template system; Spring properties substituted into templates used to generate multiple complex (not 'context') configuration files. Unless you read the walls of Spring website documentation you won't know that Spring already provides exactly that capability and so the coders involved wrote their own half-baked one.
This will be an unusual answer: the Inform documentation. It is some of the best, most compelling technical prose I've ever read. The stability of it is very calming when everything else in programming is in a perpetual state of simultaneous development and deprecation.
The two books are "Writing with Inform" and "The Inform Recipe Book":
Inform is a weird beast: it is a domain-specific language for writing interactive fiction stories, with natural English language syntax. But underneath there's an object model and datatypes and you can use it as a general-purpose language: https://learnxinyminutes.com/docs/inform7/
Additionally, there's "The Inform Designer's Manual", which is for an earlier version using a more standard programming language syntax:
Django, because there are no missing parts. Everything is documented and comes with examples, that work and most importantly it anticipates additional steps and often guides you in the right direction (if you want to dive deeper) or clearly states what's out of Django's scope.
Stripe's documentation was terrific when we were doing our initial integration. Clear descriptions, frequent use cases were described and indexed so they're easy to find, and the code samples (in 6-8 languages) are copy-paste ready using your own pre-populated credentials.
I agree, Qt is excellent. I would actually say Qt and MSDN are the best (maybe MDN too) but I have to qualify MSDN with "back when Visual Studio 6 was new". Shortly afterwards they reorganised it so everything was impossible to find and mixed in all the crap docs with the good ones.
Rust docs are decent too but not quite as good as Qt.
I like https://text-generator.io because the main SDK is either using the playground then clicking the "get code" button, or there is a one line change for people migrating in from OpenAI text generation.
Lots of good docs have you visually doing the setup/work, then you realise you can download/see a bunch of code for all the actions you did (e.g. everything UI doable is programmable and the tools taught you all the concepts), it minimises the actual programming, it is really hard/time consuming to mentaly translate API docs to code.
Strictly speaking, it's not an SDK, but postgresql's official documentation is the best I have seen. Very easy to find what you're looking for, very approachable for beginners, yet versatile for the one who needs to dig deeper.
The FreeBSD manual pages. They are thorough, accurate, and well maintained. I still refer to them on occasion even though I've not actively developed on FreeBSD for the better part of a decade now.
The Windows 3.1 SDK. I bought and read it at University, some decades ago, and I can still write simple C programs for Windows that compile under Windows 2000 and run under Windows 10.
Any SDK docs that links to, or preferably displays inline, the source code. I use the ruby docs often and they do this, displaying the ruby or C code for the method documented. Really useful, as I wouldn't be motivated to hunt for the source, but if it's right there then I'll read it.
The man pages to NetBSD. I don't think I've seen such comprehensive documentation in all my born days. Every command, API, data structure, and concept in the base system is thoroughly documented. I managed to write a toy device driver and incorporate it into the kernel, using nothing but the man pages.
One thing I miss today, is the simplicity and ease of use of the mIRC help file. There was everything in one place, and offline. I find my self often missing something comparable. (I know of desktop tools for docs, but they didn’t quite fit for me)
When I was 10, I got my first computer. A Commodore VIC 20. The book that came with the machine taught me programming. It was very well written and already at 11 I could program quite well. I wish we could take more inspiration from that period when writing modern documentation.
I’d say Stripe. Very detailed and with helpful examples. Never needed to spend much time figuring out how to do something and I didn’t need to look for random examples on the web.
RISC OS Programmer's Reference Manual. It's very well laid out, clearly written and consistent. In fact, I even bought myself a copy all these years later to peruse for nostalgia.
Did they improve it recently ? I haven’t developed for Android in a while but it used to be terrible. Full of absolutely useless method descriptions.
For example, I remember getting frustrated because of the docs for a setTextSize method, with the helpful description “sets the text size”. Nice. Very helpful that it didn’t mention what unit the parameter was, especially since (after experimentation) it turns out the unit is not the one you would expect for a font size.
The API docs were full of that kind of ‘documentation’, setX: “Sets X”.
If you are writing documentation, please explain what method parameters and return values actually mean, what the units used are. Especially if uses a unit no one expects. For example: font sizes are usually specified in points, if you expect them to be specified in pixels you should absolutely mention that.
Yeah that's been my experience too. Tons of "flobinate(bool yes): If yes is set to true, enables flobination. Otherwise it disables it. Returns void.". Completely unhelpful.
I think this is particularly a problem with Java docs because Java IDEs auto-insert useless documentation and people think "oh great it's documented".
https://tailwindcss.com/docs/installation