- Group hub-documentation into explanation/, how-to/, and reference/ per Diátaxis - Move ifs-integration.md to new hoist-hub/ category - Add contributing/ category with Diátaxis framework explainer - Move tutorial-basics and tutorial-extras under docusaurus-guide/ - Rewrite docs/intro.mdx as site entry point with category navigation - Update all doc titles to reflect their Diátaxis type - Add HOIST logo to homepage hero and fix Get Started link
2.2 KiB
sidebar_position, title
| sidebar_position | title |
|---|---|
| 3 | Documentation Framework (Diátaxis) |
Documentation Framework (Diátaxis)
This documentation site is structured using the Diátaxis framework — a systematic approach to technical documentation that organizes content around user needs rather than product structure.
The Core Idea
Documentation serves different purposes depending on what the reader needs at a given moment. Diátaxis identifies four distinct needs and maps them to four types of documentation:
| Type | Answers | Reader is... |
|---|---|---|
| Explanation | "Why does this work this way?" | Seeking understanding |
| How-to Guide | "How do I accomplish X?" | Solving a specific problem |
| Reference | "What exactly does this field/section require?" | Consulting while working |
| Tutorial | "How do I learn this from scratch?" | Learning for the first time |
How This Site Uses Diátaxis
Explanation
Content that provides context, background, and reasoning. Read this to understand the why behind the HUB Spec Standard — its purpose, the roles involved, and the architectural decisions behind IFS integration.
How-to Guides
Step-by-step guidance for specific documentation tasks. Read these when you know what you need to document but need direction on how to do it correctly — such as documenting a UI flow, mockups, or custom fields.
Reference
Templates and structural standards for every section of a HUB spec. Consult these while writing a spec — they define what each section must contain, what fields are required, and how tables should be structured.
Why This Matters
Mixing documentation types is one of the most common causes of poor documentation. A reference page that tries to also teach and guide becomes hard to navigate. A how-to guide bloated with background theory loses its usefulness when someone needs a quick answer.
By keeping each type separate and clearly labeled, every reader — whether a new Business Analyst or an experienced Developer — can find exactly what they need without reading everything.
For a deeper understanding of the framework, visit diataxis.fr.