In my experience, the best documentation usually starts with a section called "Concepts" or something similar.
Beyond some simple floor of complexity, starting by elucidating the high-level concepts you're dealing with is really important to convey understanding. Too many docs jump straight from the introduction into the technical minutiae. The doc writer often takes for granted all the implicit mental models they've built up from repeatedly hacking on the underlying system. Without those mental models, the technical details are just meaningless facts that the user's never going to retain.
Great documentation starts by carefully explaining the core concepts not just from the system, but from the problem domain itself. This builds up a common vocabulary that allows for precision, non-ambiguity, and clarity throughout the rest of the documentation.
One of the best articles I've seen on writing documentation is "What Nobody Tells You About Documentation" [0]. It divides docs into four categories: Tutorials, How-To Guides, Discussions, and References.
I'm currently working on a major rewrite of the Redux core docs [1], and I've been taking notes on that post and various other docs writing resources [2] so I can apply them to the rewrite.
Don't forget the "Quickstart". For example if you run a weather forecast/historical data API most people probably only want "how to get weather on X day" which should be up front and center. The rest of the options such as filtering or finer tuning comes later.
Yeah, that's actually something I'm planning to add to the Redux docs shortly - a "Quick Start" tutorial page that shows things in a "top-down/how-to" approach (specifically using our new Redux Toolkit package [0] and the React-Redux hooks API [1]), vs the existing tutorial that teaches concepts "bottom-up".
I started an initial attempt to write that page [2], wasn't happy with where it was going, and stepped back to do some analysis on other docs sites first so I could nail down how i want to tackle explaining things. I'm hoping to try writing that again after I get this next version of Redux Toolkit out the door.
> API doc tends to be Euclidean, but at its best documentation is Socratic. That’s when you can really be productive—fast.
Socratic documentation is necessary, but you need both. You really do need both. When I come back to your library after a year of not using it, and I can't remember the name of a slightly obscure function, I don't want to have to dig around in prose for the sentence where you explain what it does. I want to be able to search for a few keywords and get a function definition, with the arguments and the return type listed, and a short description of what it does. (If possible, I want to be able to search by the type; the only language that I've ever seen have this feature is Haskell, even though it would be doable in any statically typed language.)
There is, however, yet another category of documentation that is increasingly common and often becoming necessary in order to cope.
I don't know if it has a formal name, but let's call it "context-sensitive" documentation. Some examples that come to mind are when you have auto-completion, "light=bulbs" or intellisense in IDE's, or -? options in the commandline.
In situations where you are just trying to get stuff done, and you forget something trivial-- it's usually not some extremely complex edge-case, it's usually something mundane that you forgot because you don't often do that particular task everyday. In such scenarios, it's infuriating to have to skim through detailed man pages that cover every damn exotic use-case of the the command in alphabetical order, nor is it pleasant to pick up a user guide that starts from the most fundamental basics.
There's room for documentation that sort-of reads you rather than the other way around. This kind of stuff has sometimes gotten a bad rap, since the days of "clippy" but it's getting better. In the IDE world, there was Resharper, and now even the Rosyln for dotnet has this stuff increasingly built in.
>Socratic - an open-inquiry meant to bring about a deeper understanding in the API user. You get the Euclidean part, but you also get a FAQ, you get recipes for common tasks, you get error conditions and possible responses, and you get working code examples.
« Euclidean - state your axioms and let users derive the rest. Easiest for the API provider, but hardest on the user. This is the most common form of documentation. You see it all the time. Each entry point in the API is sort of explained, but there’s nothing tying the whole API together. »
I agree that the last sentence describes the most common form of reference documentation.
But I think characterising it as "state your axioms and let users derive the rest" is too generous. Typically what you have to do isn't so much "derive" as "make educated guesses".
As far as I'm concerned, the problem is that most of this documentation _isn't_ stating its axioms. It's much more common for each function to have a description in terms of definitions and concepts which aren't further defined. And very often if a piece of behaviour doesn't have any knobs controlling it, it doesn't get documented at all.
I dislike the dichotomy presented here, where this form of bad documentation is on one side, and "A FAQ, recipes for common tasks, and working code examples" are on the other.
Those are all fine things to have, but they're not really a substitute for setting out directly, in the reference documentation, just what it is the software is promising to do.
This is a good point. Lists of all the options are not great. I recall... a long time ago... the GNU tar man page didn't have much in the way of examples, just descriptions of all the options.
The GNU tar man page is explicitly a shortened reference, because the real manual is in info format.
Info manuals are often examples of documentation done well, and the tar manual looks pretty decent.
For example it has sections like "Some Definitions" and "What 'tar' Does", then a tutorial, followed by the formal documentation.
It looks like it also separates the coverage of what the program does from the description of how to request those things on the command line. That's also often a sign of high quality documentation.
Fair enough; this was nearly 25 years ago on a laptop with 4 megs of ram, and no internet connection, though, so firing up emacs (I used 'jed') was kind of a PITA and I'm not sure I even had the info pages.
In those days, it would have been sufficient to have
tar czvf something.tar.gz some_directory/
tar xzvf some.tar.gz
Hmmm. Joel Spolsky and Jeff Atwood took Plato's settings for Socrates's dialogs -- under trees around classic Athens -- and made them work worldwide. StackOverflow.com
And, their attempt at the Euclidean approach -- their Documentation project -- didn't work out.
Beyond some simple floor of complexity, starting by elucidating the high-level concepts you're dealing with is really important to convey understanding. Too many docs jump straight from the introduction into the technical minutiae. The doc writer often takes for granted all the implicit mental models they've built up from repeatedly hacking on the underlying system. Without those mental models, the technical details are just meaningless facts that the user's never going to retain.
Great documentation starts by carefully explaining the core concepts not just from the system, but from the problem domain itself. This builds up a common vocabulary that allows for precision, non-ambiguity, and clarity throughout the rest of the documentation.