Documentation as Code

Problem

Documentation lives in separate wikis, Google Docs, or Confluence pages that quickly become outdated. When code changes, documentation doesn’t, leaving developers with inaccurate guides that waste time and cause confusion. There’s no easy way to review documentation changes alongside code changes or ensure they stay in sync.

Solution

Write documentation in the same repository as code, versioned together and reviewed through pull requests. This keeps docs synchronized with implementation and makes them easier to maintain and discover.

Example

This example demonstrates a project structure where documentation lives alongside source code in version control.

project/
├── src/              # Source code
├── docs/             # Documentation versioned with code
│   ├── README.md     # Getting started guide
│   ├── api.md        # API reference
│   └── architecture.md  # Architecture decisions
└── package.json

Benefits

• Keeps documentation synchronized with code through version control.
• Enables reviewing docs alongside code changes in pull requests.
• Makes documentation discoverable in the same place as code.
• Allows automated publishing and deployment of documentation.
• Easier to track documentation changes and their history.

Tradeoffs

• Requires developers to write and maintain documentation.
• Can slow down development if documentation is required for every change.
• May not be as user-friendly as dedicated documentation platforms.
• Needs tooling to generate readable documentation from markdown.
• Non-technical stakeholders may struggle with Git-based workflows.