Socratic vs. Euclidean Forms of API Documentation
highscalability.com
highscalability.com
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.
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.
[0] https://www.divio.com/blog/documentation/
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.
[0] https://redux-toolkit.js.org
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.
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.
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.
In those days, it would have been sufficient to have
tar czvf something.tar.gz some_directory/
tar xzvf some.tar.gz
Used to work on a product whose entire API documentation was merely a huge javadoc dump
Very very hard to work with - especially since the "docs" were in Java format, but the API was Python
I found that four-way distinction to be quite useful.
And, their attempt at the Euclidean approach -- their Documentation project -- didn't work out.
Most documentation has the theory. The best documentation shows examples of the common use cases.
Examples are a more wholistic way of transferring the state of mind of the implementer to the person who will use it.
There's always too much!
https://antipaucity.com/2013/10/11/theres-never-enough-docum...