When a cloud service's documentation grows without a clear organizational principle, readers waste time guessing where to find what they need. This article uses a hypothetical object storage documentation set to demonstrate how a four-type classification framework can guide directory structure, navigation labeling, and ongoing maintenance. All structural proposals in this article are the author's suggestions; source citations are limited to the framework's published definitions and theoretical basis.123
A Hypothetical Object Storage Documentation Directory
Consider a hypothetical object storage service documentation set. Suppose the current top-level navigation contains these items: Getting Started, API Reference, SDKs, Best Practices, Pricing, FAQ, and Troubleshooting. A developer who needs to upload their first file must guess whether “Getting Started” contains a guided walkthrough or a feature overview. An operations engineer looking for bucket lifecycle configuration might find it buried under “Best Practices” or scattered across multiple pages with no consistent signal about which page will answer their question. This is a hypothetical example constructed for illustration in this article. It does not describe any specific vendor’s documentation.
The problem this example represents is common in growing documentation sets: content is grouped by format, author convenience, or product feature area rather than by what the reader is trying to accomplish at that moment. A single page that opens with a conceptual overview, jumps into a configuration procedure, and closes with a parameter table is serving three different needs simultaneously. Readers cannot predict what they will find behind a navigation label, and authors cannot determine where new content belongs without re-reading existing pages.
The Diátaxis framework identifies four distinct documentation needs and four corresponding forms: tutorials, how-to guides, technical reference, and explanation. It proposes that documentation should itself be organised around the structures of those needs. The framework addresses problems related to documentation content, style, and architecture, and it is described as light-weight, easy to grasp, and straightforward to apply without imposing implementation constraints.1
In the hypothetical object storage example above, “Getting Started” conflates a tutorial with a feature overview. “Best Practices” mixes how-to procedures with explanatory context. “API Reference” may be the only section whose label reliably signals its content type. The rest of this article describes a step-by-step method for untangling this kind of structure, followed by suggestions for navigation design and maintenance planning.
Classifying Pages into Four Documentation Types
The following steps describe how to apply the four-type classification to an existing cloud service documentation set. The classification categories themselves come from the Diátaxis framework. The specific procedural steps for auditing, splitting, titling, and linking are this article’s suggestions for applying that framework in a cloud documentation context.2
Step 1
Audit every existing page and assign it a primary reader intent. If the page walks a new user through a sequence of actions designed to produce a learning outcome, it is a tutorial. If it helps an experienced user accomplish a specific goal they already have in mind, it is a how-to guide. If it provides accurate, complete technical description of an interface, parameter, or behavior, it is reference. If it builds understanding of why something works the way it does, it is explanation.2
Step 2
Identify pages that serve more than one intent. Mark each page that mixes types and note which sections belong to which category. A common pattern in cloud documentation is a page that begins with a conceptual paragraph, transitions into a step-by-step procedure, and ends with a table of configuration parameters. This page should become three separate documents, each with a single clear purpose and a title that signals its type.
Step 3
Write titles that match the documentation type. Tutorial titles should describe what the learner will achieve, such as “Upload your first object.” How-to guide titles should name the goal, such as “Configure lifecycle rules for a bucket.” Reference titles should name the subject, such as “PUT Object request parameters.” Explanation titles should frame the question, such as “How eventual consistency affects read-after-write behavior.” These example titles are hypothetical illustrations for an object storage service.
Step 4
Place each page under a corresponding top-level navigation section. This article suggests four top-level sections labeled Tutorials, How-To Guides, Reference, and Concepts. This is a recommended starting structure, not a universal requirement. Teams may adapt labels to match their audience’s vocabulary, but the underlying four-way distinction should remain visible in the navigation.1
Step 5
Add cross-links where types intersect. A how-to guide on configuring server-side encryption should link to the reference page for the relevant API parameter and to an explanation page covering encryption key management concepts. Cross-links help readers move between types without losing their place in the task they are performing.
Designing Navigation Entry Points
Once pages are classified, the next challenge is helping readers find the right starting point. This article suggests two complementary entry strategies, both of which are the author’s recommendations rather than requirements from any framework or vendor.
The first entry point is a task-based landing page. This page lists common goals as links to how-to guides. For the hypothetical object storage service, goals might include “Upload and download objects,” “Set up access control,” “Enable versioning,” and “Configure cross-region replication.” Each link points directly to a how-to guide, not to a mixed page. The page itself should contain minimal prose; its purpose is to route readers quickly to the procedure they need.
The second entry point is a learning-path page for users who are new to the service. This page sequences tutorials in a recommended order, with brief context sentences explaining why each step comes next. For example, a learning path might begin with creating a bucket, proceed to uploading an object, then cover setting permissions, and finish with enabling a lifecycle rule. Each step links to a tutorial page. The learning-path page is not itself a tutorial; it is a navigation aid that orients newcomers.
Both entry points should be accessible from the top-level navigation. The task-based landing page can be labeled “Tasks” or “Common operations” depending on the audience’s vocabulary. The learning-path page can be labeled “Start here” or “Learning path.” The key principle is that a reader should never have to choose between guessing which section contains their answer and reading every section until they find it.
The Diátaxis framework describes tutorials as learning-oriented experiences and how-to guides as goal-oriented directions. This distinction maps naturally to the two entry points: the learning path serves readers in what the framework’s foundations page calls the acquisition dimension, while the task list serves readers in the application dimension. Reference and explanation pages do not typically need their own dedicated entry points because readers reach them through cross-links from tutorials and how-to guides, or through search.23
Planning Maintenance and Review Cycles
Documentation structure degrades over time unless maintenance is planned. This section offers suggestions for aligning review cycles with documentation type. These are the author’s recommendations and are not derived from any specific vendor’s published process.
Reference pages degrade fastest because they track implementation details directly. Whenever an API endpoint changes, a parameter is added or removed, or a default value shifts, the corresponding reference page must be updated. This article suggests tying reference page reviews to the release process: each release that modifies a public interface should include a documentation review task for the affected reference pages.
Tutorials degrade when the onboarding experience changes. If the console interface is redesigned, if a required step is added or removed, or if a prerequisite changes, tutorials must be re-tested. This article suggests re-running each tutorial end-to-end whenever the product’s onboarding flow changes, even if the change seems minor. A tutorial that fails at step three erodes trust in the entire documentation set.
How-to guides are more resilient than tutorials because they assume the reader already knows the basics. However, they still need review when the procedure they describe changes. A how-to guide that references a deprecated configuration option or an outdated CLI flag will mislead experienced users who trust the documentation to be current.
Explanation pages degrade most slowly because they describe principles and design rationale rather than implementation details. However, when architectural decisions change or when a design trade-off is resolved differently, explanation pages must be revised. This article suggests reviewing explanation pages during major architectural milestones rather than on a fixed calendar schedule.
The Diátaxis framework’s foundations page describes four types as a complete enumeration: tutorials address learning, how-to guides address goals, reference addresses information, and explanation addresses understanding. Because each type serves a different need, each type also degrades at a different rate and for different reasons. Aligning maintenance triggers with documentation type, rather than applying a uniform review schedule, allows teams to focus effort where accuracy erodes fastest.3
Frequently asked questions
How do I decide whether a page about a specific feature is a tutorial or a how-to guide?
The classification is based on the reader’s primary intent, not on the subject matter. A page about encryption can be a tutorial if it guides a new user through enabling encryption for the first time, a how-to guide if it helps an experienced user configure encryption for a specific compliance requirement, a reference page if it lists all encryption-related API parameters, or an explanation if it discusses why client-side encryption differs from server-side encryption. When in doubt, ask: what is the reader trying to do when they land on this page?23
How often should documentation be reviewed and updated?
There is no fixed schedule that applies universally. This article suggests aligning review frequency with documentation type: review reference pages whenever the API or configuration surface changes, review tutorials whenever the onboarding experience changes, and review explanation pages when architectural decisions or design rationale changes. The key principle is that reference accuracy degrades fastest because it tracks implementation details directly.
Can there be more than four documentation types?
The Diátaxis framework identifies four and only four types based on two dimensions: action versus cognition, and acquisition versus application. The framework’s foundations page states that there is simply no other territory to cover. In practice, if you encounter content that seems not to fit any category, examine whether it is actually a mixed page that needs splitting rather than a genuinely new type.3
Should I create separate landing pages for different reader roles?
This article recommends starting with a task-based entry for users who know what they want to accomplish and a learning-path entry for users who are new to the service. The task-based entry can be a landing page listing common goals as links to how-to guides. The learning-path entry can be a short page that sequences tutorials in a recommended order. Both entry points should be accessible from the top-level navigation.
What exactly is Diátaxis?
Diátaxis is described as a systematic approach to technical documentation authoring. It prescribes approaches to content, architecture, and form that emerge from a systematic understanding of documentation user needs. It identifies four distinct needs and four corresponding forms of documentation, and proposes that documentation should be organised around the structures of those needs.1