Documentation Standards¶


What	Keeping living documentation inside every repository, and maintaining this playbook itself.
Owner	Engineering (repo docs), with this playbook maintained by its designated owners.
Triggers	Whenever code or a process changes.

Summary¶

Documentation is treated as part of the product, not an afterthought. Each codebase keeps its own documentation committed inside the same Git repository, as Markdown and Mermaid diagrams, and it is updated whenever the code changes (in the same pull request). This keeps docs versioned with the code, reviewable, and readable by both people and AI tools. This playbook is a separate, organization-wide site maintained the same disciplined way.

Full detail¶

In-repo documentation¶

Each repository contains its own documentation, committed alongside the code.
Use Markdown for prose and Mermaid for diagrams, so everything is text in version control: diffable, reviewable, and editable in the same flow as code.
Documentation is updated whenever a change affects it, in the same pull request as the change. A behavior change with stale docs is an incomplete change.
This format is also chosen so AI tools can read the docs for accurate context and help keep them current (see AI-Assisted Development).

What belongs in repo docs¶

Architecture overview and key diagrams (Mermaid).
Setup and run instructions.
API or interface documentation.
Runbooks for operational tasks (see the runbook template).
Anything a new engineer or an AI assistant would need to work in the repo safely.

flowchart LR
    A[Code change in PR] --> B{Affects behavior or setup?}
    B -->|yes| C[Update Markdown / Mermaid in same PR]
    B -->|no| D[No doc change needed]
    C --> E[Reviewed together with code]
    E --> F[Docs stay current with code]

This playbook¶

This SDLC playbook is a separate, global site, independent of any single codebase, so it can grow to cover the whole organization over time.
It is maintained like code: changes go through merge requests and review, so the Git history is the change log.
When a real process changes, the relevant page changes in the same cycle. Process deviations raised in the Monthly Retrospective are reflected back here.
It is built as a static site (MkDocs Material) and can be hosted anywhere later without changing the content.

Example¶

A developer changes how authentication tokens are refreshed. In the same PR as the code, they update the repo's docs/auth.md and the Mermaid sequence diagram of the refresh flow. The reviewer checks both the code and the doc. Later, an AI assistant reading the repo gets the correct, current flow rather than a stale one.