docs: reorganize site structure using Diátaxis framework
- 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
This commit is contained in:
1 parent
2cfb6f5ef7
commit
b9a194f7c5
44 files changed
+200
-63
No files matched your search
@@ -0,0 +1,38 @@
|
||||
---
|
||||
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/).
|
||||
Reference in new issue
Block a user