
Socratic vs. Euclidean Forms of API Documentation - zdw
http://highscalability.com/blog/2020/2/24/socratic-vs-euclidean-forms-of-api-documentation.html
======
dcolkitt
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.

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

[0]
[https://www.divio.com/blog/documentation/](https://www.divio.com/blog/documentation/)

[1]
[https://github.com/reduxjs/redux/issues/3592](https://github.com/reduxjs/redux/issues/3592)

[2]
[https://github.com/reduxjs/redux/issues/3609](https://github.com/reduxjs/redux/issues/3609)

~~~
ampdepolymerase
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.

~~~
acemarke
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.

[0] [https://redux-toolkit.js.org](https://redux-toolkit.js.org)

[1] [https://react-redux.js.org/api/hooks](https://react-
redux.js.org/api/hooks)

[2]
[https://github.com/reduxjs/redux/pull/3675](https://github.com/reduxjs/redux/pull/3675)

------
lalaithion
> 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.)

~~~
patrickmay
You seem to be describing the difference between a User Guide and a Reference
Manual. Both are needed.

~~~
crispyambulance
You're right that both of these forms are needed.

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.

------
mjw1007
« 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.

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

~~~
mjw1007
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.

~~~
davidw
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
    

In the man page.

------
warrenm
The Euclidean form is what you get with a minimalistic javadoc output

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

------
csense
This reminds me of the article talking about the four different kinds of
documentation:
[https://news.ycombinator.com/item?id=21289832](https://news.ycombinator.com/item?id=21289832)

I found that four-way distinction to be quite useful.

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

------
m463
examples. examples. examples.

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.

~~~
warrenm
There's never enough!

There's always too much!

[https://antipaucity.com/2013/10/11/theres-never-enough-
docum...](https://antipaucity.com/2013/10/11/theres-never-enough-
documentation-theres-too-much-documentation/#.Xl1w_RdOmhY)

