Files
wiki-hoist/docs/contributing/diataxis-framework.md
T
jaime.meza b9a194f7c5 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
2026-06-18 14:50:15 -05:00

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.