Writing good docs, the right way

October 29, 2019

I was pointed to this guide on writing effective software documentation recently. It’s a fruitful lens that could be applied to Systems also. 

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

Typically doc writing doesn't fail because people aren't trying, we all try, but because of how it's done. For software there are 4 kinds of docs: Tutorial, How-to, Explanation, Reference. In a successfully documented project each is written differently and stored distinctly.

Tutorials are learning oriented.

How-to's are goal oriented.

Explanations are understanding oriented.

References are information oriented.

I've watched many of my guides get tangled up, ending up more confusing the more clarity and correctness I attempt to add. It’s clear to me now that this particularly happens when mixing 'splaining and recipe-ing.