What nobody tells you about documentation

https://www.divio.com/en/blog/documentation/

by fagnerbrack • 9 years ago

37 5 9 years ago

tsycho• 9 years ago

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

NewsAware• 9 years ago

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.

mjw1007• 9 years ago

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• 9 years ago

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/

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

JdeBP• 9 years ago

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

What nobody tells you about documentation

Related Stories