- 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
39 lines
2.2 KiB
Markdown
39 lines
2.2 KiB
Markdown
---
|
|
sidebar_position: 3
|
|
title: Documentation Framework (Diátaxis)
|
|
---
|
|
|
|
# Documentation Framework (Diátaxis)
|
|
|
|
This documentation site is structured using the [Diátaxis framework](https://diataxis.fr/) — 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](https://diataxis.fr/).
|