News for hackers. Stuff that matters.
Re:What nobody tells you about documentation by mjw1007 on Thursday December 07, 2017 @02:16PM (#15873053)
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.

Re:What nobody tells you about documentation by stephenfin on Thursday December 07, 2017 @04:17PM (#15874334)
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/

Re:What nobody tells you about documentation by JdeBP on Thursday December 07, 2017 @05:42PM (#15875078)
"nobody" is attention-getting hyperbole. People have been explaining the differences between (say) Wikipedia, Wikibooks, and Wikiversity for years, now.
Re:What nobody tells you about documentation by NewsAware on Thursday December 07, 2017 @02:05PM (#15872950)
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.
Re:What nobody tells you about documentation by tsycho on Thursday December 07, 2017 @12:12PM (#15871785)
Good article with actionable advice. I wonder if anyone has good templates to do something like this for technical docs for libraries.