I like the Diátaxis framework for project documentation. So I’m giving it a shout out here!
Documentation is four things
- Tutorials: <30min, hands-on, fail quickly
- Guides: main meat, focused on use cases. Why does it exist?
- Explainers: conceptual, high-level. How does it work?
- References: the technical “contract”: public APIs, interfaces, and when and why they should change.
As you can see from the map:
- tutorials and how-to guides are concerned with what the user does (action)
- reference and explanation are about what the user knows (cognition)
On the other hand:
- tutorials and explanation serve the acquisition of skill (the user’s study)
- how-to guides and reference serve the application of skill (the user’s work) [1]
Tutorials
A tutorial is a lesson, that takes a student by the hand through a learning experience. A tutorial is always practical: the user does something, under the guidance of an instructor. A tutorial is designed around an encounter that the learner can make sense of, in which the instructor is responsible for the learner’s safety and success. [1]
Jacob Kaplan-Moss adds something that resonates: tutorials should not be too easy. “There’s always going to be a class of users who aren’t really qualified to use your project. Someone who’s never written any code before isn’t going to get very far with Django; those types of users should fail quickly. Don’t get them through the tutorial only to run into a wall later on” [2].
“Let the world benefit from your work”
Richard W Hamming wrote about one’s work:
… you can either do it in such a fashion that people can indeed build on what you’ve done, or you can do it in such a fashion that the next person has to essentially duplicate again what you’ve done …
… it is not sufficient to do a job, you have to sell it. “Selling” to a scientist is an awkward thing to do. It’s very ugly; you shouldn’t have to do it. The world is supposed to be waiting, and when you do something great, they should rush out and welcome it. But the fact is everyone is busy with their own work. You must present it so well that they will set aside what they are doing, look at what you’ve done, read it, and come back and say, “Yes, that was good.”
… ask why you read some articles and not others. You had better write your report so when it is published … as the readers are turning the pages they won’t just turn your pages but they will stop and read yours. If they don’t stop and read it, you won’t get credit.
You have to learn to write clearly and well so that people will read it, you must learn to give reasonably formal talks, and you also must learn to give informal talks.
From “You and Your Research”. [3]