|
1 | | -<ComingSoon /> |
| 1 | +--- |
| 2 | +title: Document Structure and Formatting |
| 3 | +sidebar_label: "3. Document Structure and Formatting" |
| 4 | +description: "Learn how to structure documentation using the modern Diátaxis framework, ensuring users can find and use content efficiently based on their goals." |
| 5 | +image: /tutorial/img/tutorials/technical-writer/structure-and-formatting-cover.png |
| 6 | +--- |
| 7 | + |
| 8 | +import { FaBook, FaWrench, FaCode, FaLightbulb } from 'react-icons/fa'; |
| 9 | + |
| 10 | +Writing well is only half the battle. If your users can't find the information they need, or if the content they find mixes learning materials with quick facts, your documentation fails. |
| 11 | + |
| 12 | +**Information Architecture (IA)** is the practice of organizing and labeling content so users can find what they need. The most effective modern approach to technical documentation IA is the **Diátaxis Framework**. |
| 13 | + |
| 14 | +:::tip Information Architecture Overview |
| 15 | + |
| 16 | +<br /> |
| 17 | + |
| 18 | +```mermaid |
| 19 | + graph TD |
| 20 | + A[Information Architecture ] --> B[Organizing & Labeling Content] |
| 21 | + A --> C[Goal: Help Users Find What They Need] |
| 22 | + A --> D[Modern Approach → Diátaxis Framework] |
| 23 | +
|
| 24 | + %% Diátaxis Core Branches |
| 25 | + D --> D1[1️⃣ Tutorials<br>Learning-Oriented Guides] |
| 26 | + D --> D2[2️⃣ How-To Guides<br>Task-Oriented Instructions] |
| 27 | + D --> D3[3️⃣ Reference<br>Information-Oriented Docs] |
| 28 | + D --> D4[4️⃣ Explanation<br>Understanding-Oriented Articles] |
| 29 | +
|
| 30 | + %% Sub-details for Tutorials |
| 31 | + D1 --> D1a[Step-by-step walkthroughs] |
| 32 | + D1 --> D1b[Clear learning outcomes] |
| 33 | +
|
| 34 | + %% Sub-details for How-To Guides |
| 35 | + D2 --> D2a[Goal-driven workflows] |
| 36 | + D2 --> D2b[Practical, specific results] |
| 37 | +
|
| 38 | + %% Sub-details for Reference |
| 39 | + D3 --> D3a[API Docs, CLI Commands] |
| 40 | + D3 --> D3b[Precise, factual content] |
| 41 | +
|
| 42 | + %% Sub-details for Explanation |
| 43 | + D4 --> D4a[Concepts, Principles] |
| 44 | + D4 --> D4b[“Why” behind functionality] |
| 45 | +
|
| 46 | + %% IA Systems connection |
| 47 | + A --> E[IA Systems] |
| 48 | + E --> E1[Organization System] |
| 49 | + E --> E2[Navigation System] |
| 50 | + E --> E3[Labeling System] |
| 51 | + E --> E4[Search System] |
| 52 | +
|
| 53 | + %% Relationships |
| 54 | + E1 --> D |
| 55 | + E2 --> D |
| 56 | + E3 --> D |
| 57 | + E4 --> D |
| 58 | +``` |
| 59 | + |
| 60 | +In this diagram, you can see how the Diátaxis framework fits into the broader context of Information Architecture (IA) systems, which include organization, navigation, labeling, and search systems. Each of these systems plays a crucial role in ensuring that users can efficiently find and utilize the documentation they need. |
| 61 | + |
| 62 | +::: |
| 63 | + |
| 64 | +--- |
| 65 | + |
| 66 | +## The Diátaxis Framework: Structuring by Need |
| 67 | + |
| 68 | +The Diátaxis framework is a systematic approach that categorizes all documentation into four distinct types, based on the user's current goal: **are they learning or working?** and **do they need action or cognition (knowledge)?** |
| 69 | + |
| 70 | +This prevents the single biggest problem in documentation: mixing content types (e.g., putting a conceptual explanation inside an installation guide). |
| 71 | + |
| 72 | +### The Four Quadrants of Diátaxis |
| 73 | + |
| 74 | +| Type | User Goal | Content Focus | When to Use | |
| 75 | +| :--- | :--- | :--- | :--- | |
| 76 | +| **1. Tutorials** | **Learning.** The user is a beginner and wants to learn through practice. | Guided, step-by-step action; minimum theory. | Onboarding a new user; introducing a core workflow. | |
| 77 | +| **2. How-To Guides** | **Working.** The user knows the product and wants to achieve a specific task (a "recipe"). | Solutions to real-world problems; task-focused steps. | Guides for a specific setup (e.g., "How to integrate with Slack"). | |
| 78 | +| **3. Reference** | **Working.** The user needs a precise fact about the system for quick look-up. | Factual, structured information (API parameters, configuration options). | API Documentation, configuration tables, command line syntax. | |
| 79 | +| **4. Explanation** | **Learning.** The user wants to understand the *why* and the *how* of the system deeply. | Theoretical and contextual discussion; big picture; rationale. | Design principles, architecture overviews, technical background. | |
| 80 | + |
| 81 | +<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 my-6"> |
| 82 | + <SkillCard |
| 83 | + title="Tutorials" |
| 84 | + description="Learning by doing (Action + Study). You are the instructor." |
| 85 | + icon={<FaBook className="text-pink-500 w-6 h-6" />} |
| 86 | + /> |
| 87 | + <SkillCard |
| 88 | + title="How-To Guides" |
| 89 | + description="Applying a skill to solve a problem (Action + Work). You are the chef with a recipe." |
| 90 | + icon={<FaWrench className="text-yellow-500 w-6 h-6" />} |
| 91 | + /> |
| 92 | + <SkillCard |
| 93 | + title="Reference" |
| 94 | + description="Finding facts quickly (Cognition + Work). You are the dictionary." |
| 95 | + icon={<FaCode className="text-green-500 w-6 h-6" />} |
| 96 | + /> |
| 97 | + <SkillCard |
| 98 | + title="Explanation" |
| 99 | + description="Deepening understanding (Cognition + Study). You are the thought leader." |
| 100 | + icon={<FaLightbulb className="text-blue-500 w-6 h-6" />} |
| 101 | + /> |
| 102 | +</div> |
| 103 | + |
| 104 | +### Why This Matters |
| 105 | + |
| 106 | +By adopting a framework like Diátaxis, you ensure that: |
| 107 | + |
| 108 | +1. **Users find the right content:** A new user looking to learn goes straight to 'Tutorials' instead of struggling with 'Reference' material. |
| 109 | +2. **Content stays focused:** Your 'How-To Guide' only contains steps (actions), not long conceptual paragraphs (explanations). |
| 110 | +3. **Your documentation is complete:** The framework acts as an audit checklist, exposing missing content types (e.g., "We have great tutorials, but no theoretical 'Explanation' for the architecture"). |
| 111 | + |
| 112 | +--- |
| 113 | + |
| 114 | +## Best Practices for Page-Level Formatting |
| 115 | + |
| 116 | +While Diátaxis manages the macro-structure (folders and navigation), consistent formatting manages the micro-structure (the page itself). |
| 117 | + |
| 118 | +### 1. Headings (H1, H2, H3) |
| 119 | + |
| 120 | +Use headings to create a clear, nested hierarchy that helps users scan the page. The goal is that a user should be able to read only the headings and still understand the flow of the document. |
| 121 | + |
| 122 | +* **H1 (`#`):** Used only once per page (the title). |
| 123 | +* **H2 (`##`):** Main sections of the document. |
| 124 | +* **H3 (`###`):** Sub-steps or topics within an H2 section. |
| 125 | + |
| 126 | +### 2. Lists and Steps |
| 127 | + |
| 128 | +Procedural information must be instantly digestible. |
| 129 | + |
| 130 | +| Type | Purpose | Example | |
| 131 | +| :--- | :--- | :--- | |
| 132 | +| **Numbered Lists** | For sequential steps (e.g., installation). **Always use these for tasks.** | `1. Run the command.` `2. Check the output.` | |
| 133 | +| **Bullet Lists** | For non-sequential items (e.g., features, requirements, key concepts). | `- Feature A` `- Feature B` | |
| 134 | +| **Definition Lists** | Use tables or bold formatting for key/value pairs (e.g., API parameters). | **`--config`** | The path to your configuration file. | |
| 135 | + |
| 136 | +### 3. Code Blocks and Inline Code |
| 137 | + |
| 138 | +Code is the most critical element. Always use the appropriate formatting: |
| 139 | + |
| 140 | +* **Inline Code:** Use single backticks (`` ` ``) for file names, variable names, command flags, and error messages. |
| 141 | + * *Example:* The variable `` `API_KEY` `` must be set in `` `config.env` ``. |
| 142 | +* **Code Blocks:** Use triple backticks (`` ``` ``) with language highlighting for larger code examples, scripts, or command line output. |
| 143 | + * *Example:* |
| 144 | + ```bash |
| 145 | + # Always specify the language (e.g., bash, json, javascript) |
| 146 | + npm install codeharborhub-cli |
| 147 | + ``` |
| 148 | + |
| 149 | +:::tip Use Admonitions for Clarity |
| 150 | +Use Docusaurus's built-in admonition blocks (like this tip box, or `:::note`, `:::warning`) to draw the user's attention to critical, supplementary, or conditional information without disrupting the main flow of the steps. |
| 151 | +::: |
0 commit comments