Focus writing based on content type
Question | Tutorial | How-To | Reference | Explanation |
---|---|---|---|---|
What is the user’s goal? | Learn through practice | Solve a specific problem | Find precise information | Understand concepts |
What is the user’s knowledge? | Beginner | Intermediate | Experienced | Any level |
What is the primary focus? | Learning by doing | Achieving a goal | Providing information | Deepening understanding |
How is the content structured? | Step-by-step | Problem-solution | Organized facts | Conceptual discussions |
Is it task-oriented? | Yes, guided tasks | Yes, specific tasks | No, informational | No, conceptual |
Is it designed for linear progression? | Yes | No | No | No |
Reference documentation should be super scannable. As a developer, you want to find ‘how do I do this specific task.’ When I get there, I want to be able to clearly understand the parameters. - Sarah Edwards, Documentation Engineer at Datastax
For complex or multi-threaded releases that touch many parts of your product, you need to provide both practical guidance and conceptual understanding in your documentation. Users need to grasp when and why to use something, not just how. - CT Smith, Head of Docs at Payabli
The trap is to think one framework can rule them all. Don’t be so inflexible in enforcing content types that you forget the reader. - CT Smith, Head of Docs at Payabli