# 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.