Content Types
Focus writing based on content type
Documentation needs to be organized around the specific goal you’re trying to help the user achieve.
In this article, you’ll learn the different content types, when to use each one, and how to approach writing each type.
Categorize using the Diataxis framework
The Diataxis framework is a helpful guide for categorizing content based on your audience’s needs. Documentation can generally be mapped into one of these types:
- Tutorials: Learning-oriented content for new users
- How-to guides: Task-oriented guidance for specific problems
- Explanations: Understanding-oriented conceptual discussions
- Reference: Information-oriented technical descriptions
Defining content types helps you plan documentation with a clear purpose and makes it easier for users to find what they need.
Picking a 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 |
Writing for each type
Tips and tricks
- Maintain Purpose: Before writing, assign each page a specific content type and make it top of mind in the doc throughout your writing.
- Consider Content Freshness: Regardless of content type, try to optimize for evergreen documentation. As Ethan from GitHub says, “If something represents a moment in time of what a feature looks like on a specific date, it’s probably better suited for a blog post than in the docs.” Or if something changes very frequently, such as pricing information, avoid putting it in your docs.
- Think Like Your Users: Consider different user personas when organizing content. Check out “Know Your Audience”[hyperlink] for more information.
While the Diataxis framework provides a starting point, successful documentation requires contextual adaptation to your product. Start by understanding the framework’s principles, then adjust them to serve your users’ needs.
“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