Docs as code

What it is

Docs as code stores and reviews documentation in version control alongside the work it describes, commonly using Markdown and diagrams expressed as code such as Mermaid.

Why it exists

Technical decisions, runbooks, API documentation, and release notes decay when they live outside the delivery workflow. Pull-request review, validation, and publication automation keep them closer to the change.

Key ideas

• Treat documentation changes as reviewable deliverables with owners and acceptance criteria.
• Use Markdown for portable text and Mermaid for diagrams that can be diffed and reviewed.
• Generate release notes from work items, pull requests, tags, and Git history, then edit the result for accuracy and audience.
• Keep secrets, personal data, and internal-only operational details out of public documentation and generated release notes.

Related

pull-request · devops-traceability · release-notes-templates