Tag: how-to

A Theory of Documentation

~ cafebedouin

“Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances – so software usually needs them all.

And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.”

—Daniele Procida, “What nobody tells you about documentation.” Divio. Accessed: November 12, 2018.

Probably applicable to any kind of documentation process you need to replicate, not just for software.

Classy & Disagreeable

~ cafebedouin

“The most obvious advantage of classifying the forms of disagreement is that it will help people to evaluate what they read. In particular, it will help them to see through intellectually dishonest arguments. An eloquent speaker or writer can give the impression of vanquishing an opponent merely by using forceful words. In fact that is probably the defining quality of a demagogue. By giving names to the different forms of disagreement, we give critical readers a pin for popping such balloons.”

—Paul Graham. “How to Disagree.” paulgraham.com. March 2008.

Classification also helps with determining whether it’s worth talking at all. If you aren’t at DH4 or above, is there any point in continuing the conversation?