68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
|
# Human-Facing Documentation UX Specification
|
||
|
|
|
||
|
|
## 1. Information Architecture (Directory Structure)
|
||
|
|
|
||
|
|
The documentation should follow the Diataxis framework but be organized in a way that aligns with a developer's mental model, starting from a high-level overview and allowing for deep dives into specific domains.
|
||
|
|
|
||
|
|
```text
|
||
|
|
docs/
|
||
|
|
├── index.md # Landing page (High-level architecture & entry points)
|
||
|
|
├── architecture/ # Progressive Disclosure: High-level concepts
|
||
|
|
│ ├── index.md
|
||
|
|
│ ├── system-context.md # C4 Context / System overview
|
||
|
|
│ └── data-flow.md # Mermaid diagrams of data movement
|
||
|
|
├── tutorials/ # Learning-oriented (Step-by-step guides for onboarding)
|
||
|
|
│ ├── index.md
|
||
|
|
│ └── local-setup.md
|
||
|
|
├── how-to/ # Problem-oriented (Recipes for specific tasks)
|
||
|
|
│ ├── index.md
|
||
|
|
│ ├── deploy-new-service.md
|
||
|
|
│ └── debug-helm-chart.md
|
||
|
|
├── explanation/ # Understanding-oriented (Why things are the way they are)
|
||
|
|
│ ├── index.md
|
||
|
|
│ └── decisions/ # ADRs (Architecture Decision Records)
|
||
|
|
└── reference/ # Information-oriented (Auto-generated deep dives)
|
||
|
|
├── index.md
|
||
|
|
├── helm-charts/ # Helm value schemas and usage
|
||
|
|
└── terraform/ # Module inputs/outputs and resources
|
||
|
|
```
|
||
|
|
|
||
|
|
## 2. Visual Hierarchy
|
||
|
|
|
||
|
|
To prevent the documentation from feeling like a dense text dump, we must use visual elements to create a clear hierarchy and break up the content.
|
||
|
|
|
||
|
|
* **Headers:** Use `H1` (`#`) strictly for the document title. Use `H2` (`##`) for major sections and `H3` (`###`) for subsections. Do not go deeper than `H4`.
|
||
|
|
* **Mermaid Diagrams:** Use diagrams early in `architecture` and `explanation` documents. Visuals should precede dense text to set the context.
|
||
|
|
* **Callouts/Admonitions:** Use blockquotes or specialized markdown extensions (like GitHub's alert syntax) for critical information to draw the eye.
|
||
|
|
* `> [!NOTE]` for general tips.
|
||
|
|
* `> [!WARNING]` for destructive actions or important caveats.
|
||
|
|
* `> [!TIP]` for best practices.
|
||
|
|
* **Tables:** Use tables strictly for structured data, such as environment variables, API parameters, or Helm chart values. Do not use tables for layout.
|
||
|
|
* **Code Blocks:** Always specify the language for syntax highlighting (e.g., `bash`, `yaml`, `hcl`). Keep code blocks concise; link to the actual source file if the snippet exceeds 30 lines.
|
||
|
|
|
||
|
|
## 3. Navigation
|
||
|
|
|
||
|
|
Navigation must be explicit and prevent the user from hitting "dead ends."
|
||
|
|
|
||
|
|
* **Breadcrumbs:** Every page (except the root `index.md`) should begin with a breadcrumb trail back to the root and its parent category.
|
||
|
|
* *Example:* `[Home](../index.md) > [Reference](./index.md) > Helm Charts`
|
||
|
|
* **Table of Contents (TOC):** Any document longer than two screens of text must include a generated TOC immediately following the title.
|
||
|
|
* **Next Steps/See Also:** Every document must end with a "Related Links" or "Next Steps" section. For example, a "How-To" on deploying a service should link to the "Reference" for the specific Helm chart used.
|
||
|
|
* **Index Pages:** Every directory must contain an `index.md` that lists and briefly describes all documents within that directory. It serves as the local "table of contents."
|
||
|
|
|
||
|
|
## 4. Progressive Disclosure
|
||
|
|
|
||
|
|
The documentation must cater to both the new hire needing a high-level overview and the senior engineer debugging a specific Terraform state.
|
||
|
|
|
||
|
|
1. **Level 1: The Landing Page (`docs/index.md`)**
|
||
|
|
* Goal: Orient the user.
|
||
|
|
* Content: A brief summary of the monorepo's purpose, a high-level Mermaid C4 Context diagram, and prominent links to the four Diataxis quadrants.
|
||
|
|
2. **Level 2: The Domain Overview (`architecture/index.md`)**
|
||
|
|
* Goal: Explain how the pieces fit together.
|
||
|
|
* Content: System architecture diagrams, data flow descriptions, and links to the underlying infrastructure components.
|
||
|
|
3. **Level 3: Component Deep Dive (e.g., `reference/helm-charts/my-service.md`)**
|
||
|
|
* Goal: Provide exhaustive detail for implementation.
|
||
|
|
* Content: Auto-generated tables of values, specific configurations, and links to the actual source code.
|
||
|
|
|
||
|
|
**The Golden Rule:** Never show Level 3 information on a Level 1 or 2 page. Provide summaries and clear links to drill down into the specifics.
|