dev-intel-v2/docs/human-ux-spec.md

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.

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.