Documentation As Code

DOCUMENT TYPE          | LOCATION               | FORMAT     | AUDIENCE
-----------------------|------------------------|------------|----------
API reference          | Generated from code    | OpenAPI/   | Developers
                       | annotations            | JSDoc/etc  | (consumers)
                       |                        |            |
Architecture decisions | docs/adr/              | Markdown   | Engineering
                       |                        |            | team
                       |                        |            |
Onboarding guide       | docs/guides/           | Markdown   | New team
                       |                        |            | members
                       |                        |            |
Runbooks               | docs/runbooks/         | Markdown   | On-call
                       |                        |            | engineers
                       |                        |            |
Component README       | Next to the code       | Markdown   | Contributors
                       | (src/auth/README.md)   |            |
                       |                        |            |
Changelog              | CHANGELOG.md (root)    | Markdown   | All consumers
                       |                        |            |
Configuration guide    | docs/config/           | Markdown   | Ops/DevOps
                       |                        |            |
Tutorials              | docs/tutorials/        | Markdown   | New users
                       |                        |            |
Inline code docs       | In source files        | Comments/  | Contributors
                       |                        | Docstrings |

project/
  docs/
    index.md                    # Documentation home page
    getting-started.md          # Quick start for new users
    architecture/
      overview.md               # System architecture overview
      diagrams/                 # Architecture diagrams (as code)
        system-context.puml
        container.puml
    adr/                        # Architecture Decision Records
      0001-use-postgresql.md
      0002-adopt-event-sourcing.md
      template.md
    guides/
      onboarding.md             # New developer setup
      deployment.md             # How to deploy
      troubleshooting.md        # Common issues and fixes
    runbooks/
      incident-response.md
      database-failover.md
    api/
      generated/                # Auto-generated API docs
    config/
      environment-variables.md
      feature-flags.md
  src/
    auth/
      README.md                 # Module-level documentation
    payments/
      README.md
  CHANGELOG.md
  CONTRIBUTING.md
  README.md                     # Project root README

# ADR-NNNN: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-NNNN]

## Date
YYYY-MM-DD

## Context
[What is the issue that we are seeing that is motivating this decision?
What technical, business, or team constraints exist?]

## Decision
[What is the change that we are proposing and/or doing?
State the decision clearly and concisely.]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

### Neutral
- [Side effect that is neither clearly positive nor negative]

## Alternatives Considered

### [Alternative 1 Name]
[Brief description and why it was rejected]

### [Alternative 2 Name]
[Brief description and why it was rejected]

WHEN TO WRITE AN ADR:
- Choosing a database, framework, or major library
- Deciding on an architectural pattern (microservices, event sourcing)
- Making a significant trade-off (consistency vs availability)
- Adopting or dropping a tool/practice
- Any decision that a new team member would ask "why?"

ADR LIFECYCLE:
1. Author writes ADR as part of the PR that implements the decision
2. Team reviews the ADR alongside the code
3. ADR is merged when the decision is accepted
4. If superseded, update status and link to the new ADR
5. Never delete ADRs - they are a historical record

/**
 * Retrieves a user by their unique identifier.
 *
 * @param id - The UUID of the user to get
 * @returns The user object if found
 * @throws {NotFoundError} When no user exists with the given ID
 * @throws {ForbiddenError} When the caller lacks permission to view this user
 *
 * @example
 * const user = await userService.getById("550e8400-e29b-41d4-a716-446655440000");
 * console.log(user.email);
 */
async getById(id: string): Promise<User> {
  // implementation
}

LANGUAGE-SPECIFIC TOOLS:
- TypeScript/JavaScript: TypeDoc, JSDoc -> generates HTML/Markdown from annotations
- Python: Sphinx with autodoc, pdoc -> generates from docstrings
- Java/Kotlin: Javadoc, Dokka -> standard ecosystem tooling
- Go: godoc -> generates from standard comment conventions
- Rust: rustdoc -> built into the toolchain

FRAMEWORK-SPECIFIC:
- FastAPI/Pydantic: Auto-generates OpenAPI spec from type annotations
- Spring Boot: Springdoc generates OpenAPI from annotations
- GraphQL: Schema introspection generates reference docs automatically

KEY PRINCIPLE: Write documentation in the code (annotations, docstrings,
type hints), then generate the reference docs. One source of truth.

TOOLS FOR DIAGRAMS AS CODE:
- PlantUML: Rich UML and C4 model support, text-based
- Mermaid: GitHub-native rendering, simpler syntax
- D2: Modern declarative diagramming language
- Structurizr: C4 model focused, workspace-as-code

STORE DIAGRAM SOURCE IN REPO:
  docs/diagrams/system-context.puml
  docs/diagrams/container.mermaid

Generate images in CI, or use tools that render from source
(GitHub renders Mermaid natively in markdown).

## Order State Machine

    ```mermaid
    stateDiagram-v2
        [*] --> Pending: Order Created
        Pending --> Confirmed: Payment Received
        Pending --> Cancelled: Timeout (30 min)
        Pending --> Cancelled: User Cancels
        Confirmed --> Processing: Inventory Reserved
        Processing --> Shipped: Tracking Number Assigned
        Shipped --> Delivered: Delivery Confirmed
        Shipped --> Returned: Return Initiated
        Delivered --> [*]
        Returned --> Refunded: Return Received
        Refunded --> [*]
        Cancelled --> [*]
    ```

CI CHECKS FOR DOCUMENTATION:
1. Markdown linting (markdownlint) - consistent formatting
2. Link checking (markdown-link-check) - no broken internal/external links
3. Code example validation - extract and compile/lint code blocks
4. API doc freshness - regenerate and diff against committed docs
5. Spell checking (cspell) - catch typos
6. Build verification - docs site builds without errors

TRIGGER ON:
- Changes to docs/** or *.md files
- Changes to source code (may affect generated API docs)

DOCUMENTATION REVIEW:
- [ ] New public functions/methods have docstrings or JSDoc
- [ ] Changed behavior is reflected in relevant docs
- [ ] New configuration options are documented
- [ ] New environment variables are added to config guide
- [ ] API changes are reflected in OpenAPI spec
- [ ] Breaking changes are noted in CHANGELOG
- [ ] Error messages are clear enough to serve as documentation
- [ ] README is updated if setup process changed

DOCUMENTATION QUALITY:
- [ ] Content is accurate (technically correct)
- [ ] Audience is clear (who is this for?)
- [ ] Examples are working and tested
- [ ] Links are valid and point to correct targets
- [ ] No placeholder text or TODO items remaining
- [ ] Formatting is consistent with other docs
- [ ] Diagrams are updated if architecture changed
- [ ] Spelling and grammar are correct

PUBLISHING PIPELINE (on merge to main):
1. Generate API docs from source code annotations
2. Build static site (MkDocs, Docusaurus, Hugo, Sphinx)
3. Deploy to hosting (GitHub Pages, Netlify, S3, Vercel)

POPULAR DOCUMENTATION SITE GENERATORS:
- MkDocs (Material theme): Python ecosystem, excellent search
- Docusaurus: React-based, versioning built in
- Hugo: Fast builds, Go-based
- Sphinx: Python standard, rich cross-referencing
- VitePress: Vue-based, lightweight

1. TUTORIALS (Learning-oriented)
   - Guide the reader through a complete task
   - Step-by-step, hands-on
   - "Follow along and build a working example"
   - Example: "Build your first API endpoint in 15 minutes"

2. HOW-TO GUIDES (Task-oriented)
   - Solve a specific problem
   - Assume the reader already knows the basics
   - "Here is how to accomplish X"
   - Example: "How to add authentication to an endpoint"

3. REFERENCE (Information-oriented)
   - Describe the system accurately and completely
   - No narrative, just facts
   - "What are all the configuration options?"
   - Example: API reference, configuration reference

4. EXPLANATION (Understanding-oriented)
   - Provide background and context
   - Discuss alternatives and trade-offs
   - "Why does the system work this way?"
   - Example: Architecture decisions, design rationale

1. USE ACTIVE VOICE:
   Bad:  "The configuration file is read by the application on startup."
   Good: "The application reads the configuration file on startup."

2. USE PRESENT TENSE:
   Bad:  "The server will return a 404 error."
   Good: "The server returns a 404 error."

3. BE SPECIFIC:
   Bad:  "Set the timeout to a reasonable value."
   Good: "Set the timeout to 30 seconds for API calls and 5 seconds for health checks."

4. SHOW, DO NOT JUST TELL:
   Bad:  "You can configure logging levels."
   Good: "Set the LOG_LEVEL environment variable to debug, info, warn, or error:
          LOG_LEVEL=debug npm start"

5. USE CONSISTENT TERMINOLOGY:
   Pick one term and use it everywhere. Do not alternate between
   "user", "customer", "account holder", and "client" for the same concept.
   Create a glossary if terms are ambiguous.

6. FRONTLOAD IMPORTANT INFORMATION:
   Bad:  "After configuring the database connection string, setting up
          the cache layer, and enabling logging, you can start the server."
   Good: "To start the server: npm start.
          Prerequisites: database connection, cache, and logging must be configured."

METRICS:
- Documentation coverage: % of public APIs with docs
- Freshness: Average age of last update per document
- Broken link count: Total broken internal and external links
- Search success rate: % of searches that lead to a click
- Feedback score: Reader ratings or thumbs up/down
- Build pass rate: % of docs CI builds that pass
- Time to first contribution: How quickly new hires update docs

HEALTH INDICATORS:
  HEALTHY:  Docs updated in same PR as code, CI passes, < 5 broken links
  WARNING:  Docs lag code by > 1 sprint, occasional CI failures
  CRITICAL: Docs are months stale, no CI, developers say "ignore the docs"

1. DOCUMENTATION ISLAND: Docs in a separate wiki with no code connection.
   FIX: Move docs into the repository. Review alongside code.

2. WALL OF TEXT: Single massive README with no structure.
   FIX: Break into files by topic. Use headings and table of contents.

3. DOCUMENTING IMPLEMENTATION: Describing SQL queries instead of behavior.
   FIX: Document what a function does and when it fails, not how.

4. NO MAINTENANCE PROCESS: Written once, never updated, no ownership.
   FIX: Assign team ownership. Include docs in definition of done.
   Run freshness checks in CI. Schedule quarterly doc reviews.