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|
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
|Working mental model
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.