
What nobody tells you about documentation - fagnerbrack
https://www.divio.com/en/blog/documentation/
======
mjw1007
I'm not sure they've got the boundary between Reference and Explanation quite
right.

They seem to be thinking of the Explanation category as less than formal, and
of the Reference category as organised around individual items (a list of
methods, or command-line arguments, or configuration options).

What a lot of projects miss is formal, complete-and-correct documentation of
what the program does and doesn't promise to do, independent of any user-
controllable knob.

------
stephenfin
This is very similar to the advice of Jacob-Kaplan Moss, architect of the
Django documentation [1]. I used this very advice in the authoring of the Open
vSwitch documentation [2] though I, like other commenters here, did have
difficulty distinguishing between tutorials and how-tos.

[1] [https://jacobian.org/writing/what-to-
write/](https://jacobian.org/writing/what-to-write/)

[2] [http://docs.openvswitch.org/](http://docs.openvswitch.org/)

------
JdeBP
"nobody" is attention-getting hyperbole. People have been explaining the
differences between (say) Wikipedia, Wikibooks, and Wikiversity for years,
now.

------
NewsAware
Definitely a nice article. Somehow I would in a real case be hard pressed to
distinguish Tutorial and How To. When teaching a child how to cook, I would do
so by showing/helping to cook a simple meal. This would be done in a series of
steps. Very much like the definition of howto in the article.

------
tsycho
Good article with actionable advice. I wonder if anyone has good templates to
do something like this for technical docs for libraries.

