{
    "slug": "documentation",
    "term": "Code Documentation",
    "category": "general",
    "difficulty": "beginner",
    "short": "Written explanations of code intent, architecture decisions, APIs, and operational concerns — distinct from comments in source files.",
    "long": "Good documentation exists at multiple levels: inline comments for non-obvious why decisions, PHPDoc for API contracts, README files for setup and usage, Architecture Decision Records (ADRs) for significant design choices, and runbooks for operational procedures. The best documentation is up-to-date, co-located with the code it describes (or linked from it), and treats clarity as a design goal. Documentation that explains what rather than why is usually a sign the code itself should be made clearer.",
    "aliases": [
        "code documentation",
        "software docs",
        "README"
    ],
    "tags": [
        "general",
        "quality",
        "team-process",
        "communication"
    ],
    "misconception": "Good code does not need documentation. Self-documenting code explains the how; documentation explains the why — architectural decisions, non-obvious constraints, external system interactions, and operational runbooks cannot be inferred from code alone regardless of quality.",
    "why_it_matters": "Good documentation reduces the time for new team members to become productive, preserves architectural decisions, and prevents rediscovery of solved problems — it is an investment in future velocity.",
    "common_mistakes": [
        "Documentation that explains what (readable from code) instead of why (not readable from code).",
        "Docs that are out of date because they live separately from the code they describe.",
        "No ADRs (Architecture Decision Records) — future developers re-debate the same decisions without context.",
        "Over-documenting obvious code and under-documenting complex or non-obvious decisions."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "docblock",
        "comment_smell",
        "naming_conventions"
    ],
    "prerequisites": [
        "docblock",
        "documentation_as_code",
        "developer_experience"
    ],
    "refs": [
        "https://www.divio.com/blog/documentation/",
        "https://adr.github.io/"
    ],
    "bad_code": "// Documentation of what — useless:\n// Increments the counter by 1\n$counter++;\n\n// Documentation of why — valuable:\n// Counter starts at 1, not 0, because downstream billing system\n// uses 1-based page numbers and we cannot change that API contract.\n// See ADR-0042 for context.",
    "good_code": "// PHPDoc — inline API documentation\n\n/**\n * Place an order for the authenticated user.\n *\n * Validates cart contents, applies loyalty discounts, charges payment method,\n * and dispatches OrderPlaced event. The cart is cleared on success.\n *\n * @param  Cart           \\$cart    Validated cart (must not be empty)\n * @param  PaymentMethod  \\$payment Tokenised payment method\n * @return Order          The persisted order with status 'pending'\n *\n * @throws CartEmptyException      If the cart has no items\n * @throws PaymentFailedException  If the charge is declined\n */\npublic function place(Cart \\$cart, PaymentMethod \\$payment): Order {}\n\n// README structure:\n// 1. What this project does (1 paragraph)\n// 2. Quick start (copy-paste to get running)\n// 3. Environment variables (.env.example documented)\n// 4. Architecture overview\n// 5. Contributing guide",
    "quick_fix": "Document the why not the what — code shows what it does; comments should explain why a decision was made, what constraint it satisfies, or what would break if this code were changed",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/documentation",
        "html_url": "https://codeclaritylab.com/glossary/documentation",
        "json_url": "https://codeclaritylab.com/glossary/documentation.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": "[Code Documentation](https://codeclaritylab.com/glossary/documentation) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/documentation"
            }
        }
    }
}