{
    "slug": "documentation_as_code",
    "term": "Documentation as Code",
    "category": "general",
    "difficulty": "beginner",
    "short": "Treating documentation with the same discipline as code — version controlled, reviewed in pull requests, tested for accuracy, and kept close to the code it describes.",
    "long": "Documentation as Code (Docs-as-Code) means writing docs in plain text formats (Markdown, AsciiDoc, reStructuredText), storing them in the same repository as the code, reviewing them in pull requests, and generating publishable sites via CI (MkDocs, Docusaurus, Sphinx). Benefits: docs are versioned with the code they describe, changes require review, and docs never drift to a separate wiki that falls out of date. OpenAPI specs generated from code are an example of docs-as-code taken to its logical conclusion.",
    "aliases": [
        "docs-as-code",
        "documentation",
        "Markdown docs",
        "ADR"
    ],
    "tags": [
        "general",
        "documentation",
        "devops",
        "quality"
    ],
    "misconception": "A wiki is sufficient for technical documentation — wikis are disconnected from code, never reviewed alongside changes, and inevitably fall out of date; docs in the repo stay honest.",
    "why_it_matters": "Documentation stored outside the repo is almost always wrong — it describes the system as it was when written, not as it is now. Docs next to code get updated when the code changes.",
    "common_mistakes": [
        "Documentation in a separate wiki — never reviewed with code changes, guaranteed to drift.",
        "README that only covers installation but not architecture decisions or common workflows.",
        "Not including runbooks alongside the code that requires them — ops team cannot find them in an incident.",
        "Documentation written once and never maintained — schedule periodic doc reviews as part of sprint planning."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "architecture_decision_records",
        "openapi",
        "developer_experience",
        "changelog"
    ],
    "prerequisites": [
        "architecture_decision_records",
        "code_documentation_standards",
        "developer_experience"
    ],
    "refs": [
        "https://www.writethedocs.org/guide/docs-as-code/"
    ],
    "bad_code": "# Docs in Confluence — disconnected from code:\n# PR: 'Refactor payment gateway to use Stripe v3'\n# No documentation update required in PR\n# Confluence page: still describes Stripe v2 API\n# New developer follows outdated docs\n# 2 hours debugging why the old endpoints dont work",
    "good_code": "# Docs in repo — reviewed with code:\n# PR: 'Refactor payment gateway to use Stripe v3'\n# Required: update docs/payments.md alongside code changes\n# CI check: markdownlint, link checker\n# Reviewer sees doc changes alongside code changes\n# docs/adr/0012-stripe-v3-migration.md explains the why\n# New developer reads accurate, current documentation",
    "quick_fix": "Store all documentation in the same repository as the code — ADRs in docs/adr/, runbooks in docs/runbooks/, and API docs generated from OpenAPI annotations; review docs changes in the same PR as code changes",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/documentation_as_code",
        "html_url": "https://codeclaritylab.com/glossary/documentation_as_code",
        "json_url": "https://codeclaritylab.com/glossary/documentation_as_code.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Documentation as Code](https://codeclaritylab.com/glossary/documentation_as_code) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/documentation_as_code"
            }
        }
    }
}