Four Forms of Documentation

A colleague recently pointed me at this article by Daniele Procida that divides software documentation into four categories:

Most useful when studying Most useful when working
Practical steps Tutorial
How-to Guide
Theoretical knowledge Explanation

It’s a useful taxonomy, and I’ve been trying to map it onto the novice-competent-expert model. What I have so far is:

Trying to acquire/deepen knowledge Trying to accomplish specific task
Tentative mental model
Tutorial How-to Guide
Working mental model
(competent practitioner)
Explanation Reference

I’m still not satisfied with this: how-to guides are also useful for competent practitioners who (for example) have temporarily forgotten how much salt to put in the soda bread. On the other hand, I think Procida’s identification of tutorials with practical knowledge and explanations with theoretical knowledge is less useful than identifying the two audiences and the state of their mental models. I’d be very grateful for pointers to other ways of classifying different types of documentation and their theoretical underpinnings.

Later: Neil Brown commented:

  • How-to guide: what you hope to find when you google
  • Reference: for when you encounter surprising behaviour
  • Tutorial: for people who read manuals before using things
  • Explanation: something you read years after you should have, to fill in the few remaining knowledge gaps

It’s slightly tongue-in-cheek, but there’s a lot of truth in it. I’ve also written before about Mike Caulfield’s notion of a chorus of explanations, which is still the most accurate description I know of how I am using various resources as I slowly teach myself R.

In the wake of posts about Shopify's support for white nationalists and DataCamp's attempts to cover up sexual harassment
I have had to disable comments on this blog. Please email me if you'd like to get in touch.