What is the difference between docs-as-code and wiki-based documentation?

Docs-as-code means documentation is stored in the same version control system as the code it describes — typically as Markdown or AsciiDoc files in the same repository, committed alongside code changes, reviewed in the same pull request process, and deployed through the same CI/CD pipeline. Wiki-based documentation (Confluence, Notion, Google Docs, internal wikis) is stored in a separate system with its own access control, edit history, and publishing flow, decoupled from the code repository. The practical consequence of this distinction is the forcing function for updates. In a docs-as-code model, a PR that changes an API endpoint can include a diff of the updated API reference documentation in the same review; the reviewer sees both the code change and the documentation change and can flag documentation that is incomplete or inconsistent. The merge gate can require that documentation files be updated alongside code files for certain paths. In a wiki model, the documentation update is a separate action taken after the PR merges — it requires the engineer to open a second system, find the relevant page, and update it while the context of the change is still fresh. The wiki model has no enforcement mechanism: an engineer who forgets to update the wiki, or who deprioritizes it under sprint pressure, produces a divergence between the deployed system and its documentation without any automated signal. Over two to three years, the aggregate of these individual update failures accumulates into a documentation system that is partially correct for recent changes and increasingly incorrect for older content. The docs-as-code approach prevents this accumulation for content that lives in the repository, but it does not apply to operational documentation (runbooks, incident playbooks, on-call guides) that describes procedures rather than APIs — those are better maintained in a runbook system with their own testing cadence rather than in the application code repository.

How should runbook ownership be handled when engineers leave the team?

Runbook ownership transfer on engineer departure is one of the most common sources of documentation debt in engineering organizations, and it is almost never addressed in the founding documentation strategy decision. The problem has two parts: discovery and assignment. Discovery: which runbooks does the departing engineer own? This requires that runbook ownership be tracked as metadata — either a frontmatter field in the runbook document, a spreadsheet, or a CODEOWNERS-style file mapping runbooks to their owners. Without explicit ownership metadata, the departure of an engineer creates invisible orphaned runbooks — documents with no owner, no one responsible for updating them, and no one who will notice when they go stale. Assignment: who receives ownership of the orphaned runbooks? The answer depends on the organizational model, but the process must be explicit: during the offboarding checklist, the departing engineer transfers each owned runbook to a named successor, and the runbook metadata is updated before the engineer's access is revoked. A practical failure mode is runbooks that describe a procedure the departing engineer was the only person who understood. In this case, ownership transfer is insufficient — the runbook must also be reviewed against the current system state before the engineer leaves, because the departing engineer is the only person who can identify where the runbook has drifted from reality. The offboarding checklist should include a runbook review step: for each owned runbook, the departing engineer walks through the procedure with their successor and updates any steps that have drifted. This is not a documentation policy; it is a knowledge transfer protocol that happens to produce updated documentation. Organizations that treat it as documentation maintenance alone miss the knowledge transfer value, and organizations that handle knowledge transfer without updating the documentation produce runbooks that remain stale even after the handoff.

What is an undiscoverable surface in the context of engineering documentation?

The undiscoverable surface is the set of decisions, procedures, and behaviors that exist in the organization's collective knowledge but cannot be found by an engineer who does not already know where to look. It accumulates from several sources: closed Slack threads that answered important questions but are not indexed by the documentation system; PR descriptions that contain the rationale for a non-obvious implementation choice but are not linked from the code they describe; stale wiki pages that return in search results ahead of the current documentation because they were written earlier and have more inbound links; and on-call runbooks that describe the correct procedure for a system that no longer exists as described. The undiscoverable surface is distinct from undocumented knowledge — some of it is documented, but the documentation is effectively unfindable under production conditions. An on-call engineer investigating an incident at 2am will not find a Slack thread from three years ago that explains why a particular configuration value is set to an apparently arbitrary number. The undiscoverable surface grows monotonically in the absence of a deliberate policy to address it. The policies that control its growth are: a canonical documentation location policy (information about X lives in location Y, not in Slack or PR descriptions), a documentation link requirement in PRs that make non-obvious choices (the PR description must link to or update the documentation for the system being changed), and a periodic documentation audit that identifies pages that are stale, orphaned, or superseded by more recent content. The documentation strategy decision record must include a stated policy for each of these controls, or explicitly acknowledge that the undiscoverable surface is an accepted risk at the team's current scale.

How do you enforce API documentation currency in a CI pipeline?

API documentation currency enforcement in CI requires that the API contract — the set of endpoints, parameters, response types, and error codes — be expressed in a machine-readable format that can be diffed against the running implementation. The most common approach is an OpenAPI specification file (openapi.yaml or openapi.json) committed to the code repository and generated from or validated against the actual API implementation in CI. There are two generation directions: spec-first, where the OpenAPI file is the source of truth and the implementation is generated from it (via code generation tools like openapi-generator or oapi-codegen); and implementation-first, where the running application generates the OpenAPI spec at startup (via framework introspection in FastAPI, Springdoc, or NestJS's Swagger module) and CI diffs the generated spec against the committed spec file. Implementation-first with a spec diff check is the more common approach for teams that did not start spec-first: the CI job runs the application, calls the spec generation endpoint (typically /openapi.json), diffs the output against the committed spec file, and fails the build if the diff is non-empty. This forces the committed spec file to be updated whenever the implementation changes, making the spec file a reliable reflection of the deployed API. The limitation is that this approach cannot enforce the accuracy of the human-written descriptions in the spec — it verifies structural currency (correct parameters, correct types, correct response codes) but not semantic accuracy (whether the description of a parameter's behavior is still correct after a behavior change). Semantic accuracy requires human review; the CI gate can only enforce structural currency. For teams using wiki-based API documentation, the equivalent enforcement mechanism does not exist as an automated CI step. The closest available approach is a documentation completeness checklist in the PR template that includes 'API documentation updated' as a required checkbox, combined with a periodic documentation audit that compares the wiki content against the running API. Neither provides the same guarantee as a spec diff in CI.

The documentation strategy decision record: why the ownership model you chose determines your documentation freshness ceiling and your team's undiscoverable surface

Published 2026-07-12 · WhyChose

Documentation strategy decisions are made during the founding sprint or when a team first scales past five engineers — whichever comes first. The team evaluates the alternatives: Notion, Confluence, a company wiki, Markdown files in the repository, a dedicated documentation site, some combination of these. The AI session that produces the documentation platform decision is practical and specific to the team's current size. It compares the cost of setting up a static site generator against the familiarity of Notion, notes that most of the team already has Confluence accounts from previous jobs, and concludes in favor of whatever is fastest to start using. The decision also implicitly produces an ownership model: documents are owned by whoever writes them, or by the team closest to the relevant system, or by the engineering manager who is currently unblocking everything. These ownership assignments are not written down. They exist in the shared understanding of the founding team, which is accurate at the time and degrades in proportion to team growth, attrition, and the passage of time since anyone last needed to read a particular document.

What the AI session does not produce is the decision record's second half. The session answers "which platform?" and produces an initial documentation structure. It does not ask: what is the mechanism that detects when documentation has drifted from the system it describes? Who owns a document when its author leaves the company? What does "current enough" mean — how much drift between a runbook and the production system is acceptable before the runbook becomes dangerous to follow? What is the policy for documentation written in a closed Slack thread or a PR description that answers an important question but is never migrated to the canonical location? Which category of documentation must be co-located with the code it describes versus maintained in a separate system, and why? Each of these questions has an answer that is not derivable from "we use Confluence" or "we do docs-as-code." Each answer determines the rate at which documentation accumulates drift, the surface area of undiscoverable operational knowledge, and the speed at which an on-call engineer executing a runbook at 2am is operating on a lie. The answers exist in the AI session. They are the reasoning behind the platform choice. They are almost never written down.

Two ways documentation strategy decisions produce the wrong outcome

The runbook staleness story

A fintech startup with eleven engineers documents their deployment, rollback, database failover, and incident response procedures in Confluence during their founding infrastructure sprint. The head of engineering sets an explicit documentation policy: after each incident, the engineer who resolved the incident updates the relevant runbook. The policy is correct in structure — post-incident updates are the natural moment when the correct procedure is freshest in the engineer's mind, and the update cadence is self-regulating, because runbooks that are involved in incidents are the ones most likely to surface gaps. Over the following three years, the team documents every operational procedure as it is established, and post-incident runbook updates become a standard part of the retrospective process. By month thirty-six, the Confluence space contains twenty-eight runbooks covering every critical procedure: deployment rollback, database connection pool exhaustion, Kafka consumer lag recovery, Redis eviction policy change, payment provider failover, and seventeen others.

A junior engineer on their second on-call shift encounters a database connection pool exhaustion incident at 2:17am. They open the "Database connection pool exhaustion" runbook. The runbook references the admin console path /admin/db-pools to inspect current pool utilization — a path that was moved to /ops/db/pools eleven months ago during a UI consolidation sprint. The engineer spends eight minutes checking if the old path redirects (it returns 404), searching Slack for "db pools" (finding the thread announcing the UI consolidation, posted eleven months ago, which they eventually locate), and navigating to the correct path. The runbook instructs them to increase max_connections in config/database.yml — a file that was replaced by a Kubernetes ConfigMap eighteen months ago when the team migrated to Kubernetes; the actual configuration now lives in k8s/configmaps/database-config.yaml and requires a kubectl apply rather than a file edit. The engineer finds the ConfigMap after twelve additional minutes of searching. The runbook references PagerDuty escalation to the "DB lead" role — a role that was eliminated in a restructuring eight months ago; the DBA function was absorbed into the platform team, and the on-call escalation target is now the platform team's primary, not a named DB lead role. The engineer escalates to the wrong contact and waits twenty-two minutes before a second look at the org chart produces the correct escalation target. Total P0 incident duration: ninety-three minutes. Forty-seven of those minutes were caused by procedures that were accurate when the runbook was written and had not been touched since.

The post-incident retrospective identifies three documentation failures. The engineering team updates all three runbook entries. But the post-incident update policy — the founding documentation policy — was only triggered by incidents. Of the twenty-eight runbooks in the Confluence space, twenty-six had not been involved in any recent incident. Those twenty-six runbooks had accumulated seventeen to twenty-two months of drift: the same Kubernetes migration that invalidated the ConfigMap reference affected four other runbooks. The same UI consolidation that moved the admin console paths affected three others. The same restructuring that eliminated the DB lead role affected two escalation paths in runbooks covering different system components. None of these drift events triggered a documentation update, because none of them were incidents. They were routine engineering changes — migrations, restructurings, UI consolidations — that generated no signal to the documentation system. The founding policy of "update runbooks after incidents" was correct for the class of documentation failures triggered by incidents. It was silent on the class of documentation failures triggered by system changes that did not produce incidents.

The new engineering leader who inherits this runbook system will find twenty-eight runbooks in Confluence, each with an accurate last-edited date, and no information about which of them have drifted since their most recent edit. The Confluence edit history shows whether a document was updated; it does not show whether the system the document describes was updated. These are different questions, and only one of them is answerable from the documentation system itself.

The API documentation death spiral

A developer-tools SaaS company builds their first public API when they have seven engineers. The team evaluates the documentation options in an AI session: OpenAPI with a generated Redoc site (accurate but requires tooling setup that seems over-engineered for seven people), Readme.io (polished but $400/month and overkill for a beta API), Postman collections (useful for testing but not a good reading experience for integration developers), or Notion (already in use, familiar, fast to write). The team chooses Notion. The ownership model is implicit and explicit: "the engineer who writes the endpoint writes the docs." The decision is recorded in a Notion page titled "Documentation conventions," which most engineers will never read.

Two years later, the team has grown to twenty-three engineers and the API has thirty-one endpoints across four product areas. The Notion API documentation workspace has forty-nine pages. Fourteen pages have a last-edited date more than six months ago. Eight pages have never been edited since their initial creation. The endpoint POST /v1/reports/generate has a required parameter output_format whose documented valid values are pdf, csv, and xlsx. The original implementing engineer added json as a fourth valid value eighteen months ago to support a specific integration request from an enterprise customer. The engineer added the value to the application code and to the Postman collection used for internal testing, but did not update the Notion documentation page because the sprint retrospective happened two days after the change was merged and the runbook update was logged as a backlog item that was never assigned or completed.

Enterprise customers who built integrations against the published API documentation believe json is not a valid output_format value. Two customers use CSV as their output format for large report exports and apply a post-processing step to convert CSV to JSON for their downstream systems. CSV generation for a ten-thousand-row report takes 4.7 seconds; JSON generation for the same report takes 0.8 seconds. The customers' integrations are spending approximately six additional seconds per large report request on a conversion step that is unnecessary given the available output format. Three customers independently filed support tickets describing their CSV-to-JSON workaround and asking whether a native JSON format was planned. Two support engineers closed the tickets as "working as documented" because the Notion page was the authoritative source of truth for API capabilities. The third ticket was escalated to an integration engineer who discovered the discrepancy, updated the Notion page, and replied to the customer — but by that point the customer had already built their conversion pipeline and declined to change it because the sprint to remove the workaround was not worth the risk of modifying production integration code for a non-urgent optimization.

The documentation failure was not caused by Notion as a platform. The failure was caused by an ownership model that had no enforcement mechanism. The "endpoint author writes the docs" policy required a voluntary action at change time — a second system to open, a page to find, a paragraph to update — with no CI gate, no PR review requirement, no deployment blocker. Every individual failure to update the documentation was a reasonable decision under sprint pressure. The aggregate of those individual failures, across twenty-three engineers over two years, produced a documentation system that was partially correct and fully trusted — which is the most dangerous possible state. Partially correct and trusted means engineers and support teams make decisions based on documentation without questioning its currency, because the documentation looks authoritative and there is no signal that it has drifted from the running system. The ADR lifecycle decision record describes the same failure mode for architecture decision records: a record that is superseded but not marked as superseded will be read as current by future engineers who have no way to know it describes a decision that was reversed. The documentation strategy's staleness problem and the ADR lifecycle's supersession problem are the same structural failure: authoritative-looking documentation with no currency signal.

Three structural properties that documentation strategy decisions determine

The ownership gap rate and the staleness detection mechanism

Ownership assignment at document creation time produces accurate documentation at the moment of creation. What it does not produce is the mechanism that detects when the documented system has changed without a corresponding documentation update. The staleness detection mechanism — the process by which documentation drift becomes visible — is the variable that determines the useful life of documentation, not the creation date or the last-edited date. Without a detection mechanism, documentation is accurate once and increasingly wrong thereafter, on a timeline that depends on how frequently the documented system changes and how rarely the documentation is revisited.

Staleness detection mechanisms differ by documentation type. For API documentation, the detection mechanism is a CI job that diffs the deployed API contract against the committed specification — if the diff is non-empty, the documentation has drifted and the build fails. For runbooks, the detection mechanism is a periodic dry-run test: an engineer follows the runbook step-by-step in a staging environment on a regular cadence (quarterly for critical runbooks, annually for low-frequency procedures) and documents any steps that fail or are missing. For architecture documentation, the detection mechanism is a periodic architecture review: the team reads the documented architecture against the current system topology and identifies divergences. Each of these mechanisms requires scheduled engineering time, which is why they are deprioritized under sprint pressure and rarely present in the founding documentation strategy. The documentation strategy decision record must specify the detection mechanism for each documentation category, the cadence at which it runs, and the owner responsible for running it. Without these specifications, the detection mechanism is implicitly "whenever someone notices the documentation is wrong," which is a non-mechanism that produces the runbook staleness and API documentation failures described above.

The ownership gap rate — the rate at which documentation creates orphaned documents with no defined owner — is the secondary variable that determines long-term documentation health. Ownership gaps accumulate from two sources: engineers who leave without transferring their documentation ownership, and documentation written in ad-hoc locations (Slack threads, PR descriptions, meeting notes) that is never migrated to a canonical location with an assigned owner. The ownership gap rate is controlled by two policies: an offboarding protocol that includes explicit documentation ownership transfer for each document the departing engineer owns, and a canonical location policy that specifies where different types of information must live and prohibits treating non-canonical locations as authoritative. The on-call rotation design is directly coupled to the ownership gap rate: an on-call engineer executing a runbook whose documented owner left six months ago is operating on documentation that has received no maintenance for at least six months. The on-call response quality ceiling is the documentation freshness floor.

The docs-as-code versus wiki divergence rate

Documentation that lives in a wiki or a separate documentation system begins diverging from the code it describes at the moment a code change is merged without an accompanying documentation update. The divergence rate is proportional to the frequency of code changes and inversely proportional to the enforcement rate of documentation updates — the fraction of code changes that trigger a documentation update in the same review cycle. For teams without a CI-enforced documentation gate, the enforcement rate is a social norm subject to sprint pressure, and the empirical divergence rate over two to three years for active systems is high enough to render wiki-based API documentation unreliable as a primary reference for integration engineers.

Documentation that lives with the code — an OpenAPI specification committed alongside the endpoint implementation, a runbook in the same repository as the infrastructure it describes, an ADR in the same repository as the architectural component — has a structural enforcement advantage: the PR that changes the code can include a diff of the documentation change, and the reviewer can check documentation completeness as part of the code review. This does not guarantee documentation updates; it creates a natural checkpoint at which updates can be reviewed and flagged. The enforcement strength depends on whether the PR template requires documentation updates as a review criterion and whether the CI pipeline includes a documentation completeness check for the relevant file paths. Teams that adopt docs-as-code without updating their PR template or CI checks gain the co-location benefit but not the enforcement benefit — the documentation lives in the repository but the update discipline is still a social norm.

The wiki-versus-code decision is not binary. The practical partition that most teams arrive at, deliberately or not, is: API specifications and code-level documentation live in the code repository; operational documentation (runbooks, playbooks, escalation paths, environment configuration guides) lives in a wiki; architecture documentation (ADRs, system design documents, data flow diagrams) lives in either location depending on team preference. The documentation strategy decision record should make this partition explicit, including the rationale for each category's location, the enforcement mechanism for each category, and the policy for when content crosses categories — for example, when a runbook must reference a specific API endpoint, or when an architecture decision requires a change to an operational runbook.

The undiscoverable surface accumulation rate

The undiscoverable surface is the set of decisions, procedures, and system behaviors that exist in the organization's collective knowledge but cannot be reliably found by an engineer who does not already know where to look. It accumulates from several sources: Slack threads that answered operational questions but were never migrated to canonical documentation; PR descriptions that contain the rationale for a non-obvious implementation choice but are not linked from any discoverable location; stale wiki pages that appear at the top of search results because they were written earlier and have more inbound links than the current documentation; and documentation that describes how a system worked before a migration, now misleading engineers into following procedures that apply to a system state that no longer exists.

The undiscoverable surface grows monotonically in the absence of deliberate controls. Three controls limit its growth. First, a canonical location policy: each type of information has exactly one authoritative location, and engineers are expected to write information in that location rather than in Slack, PR descriptions, or personal notes. The policy must specify the canonical locations for common information types (API documentation lives in the spec file, operational procedures live in the runbook system, architectural decisions live in the ADR directory) and must include a process for migrating important information from non-canonical locations to canonical ones when it is discovered there. Second, a PR documentation link requirement: PRs that change a system's behavior in a non-obvious way must include a link to the documentation that describes the new behavior, or a link to the documentation update in the same PR. This policy surfaces the documentation gap at review time rather than after the PR merges. Third, a periodic documentation audit: on a regular cadence (quarterly for critical documentation, annually for lower-frequency content), the team reviews the documentation for owned systems against the current system state and identifies pages that are stale, orphaned, superseded, or missing. The audit produces a prioritized list of documentation gaps, not a completed remediation — the goal is visibility, not perfection. The decisions never written down dynamic is the documentation strategy's most serious downstream failure: when the undiscoverable surface is large, new engineers cannot reconstruct the reasoning behind non-obvious system behaviors, incident investigators cannot find the historical context that explains why a system is configured the way it is, and the organization's accumulated engineering judgment becomes locked inside the heads of senior engineers who were present when the decisions were made.

Three AI session types that embed documentation strategy decisions without documenting them

The documentation platform selection session is where the platform choice is made and the ownership model is implicitly set. The session evaluates Notion, Confluence, a static site generator, wiki platforms, and documentation-as-code tools, and concludes in favor of whichever combination minimizes friction for the team at its current size. The session produces a clear answer to "where does our documentation live?" and produces the initial documentation structure. What the session does not produce is the staleness detection specification: what mechanism will detect when documentation has drifted from the system it describes, who is responsible for running that mechanism, and on what cadence? It does not produce the ownership transfer protocol: what happens to documents when their author leaves? It does not produce the canonical location policy: what is the authoritative source for each type of information, and what happens to information that ends up in a non-authoritative location? These policies are not part of "the documentation platform" in the way teams usually frame the question; they are the operational commitments that determine whether the platform choice produces accurate, discoverable documentation over three years, or produces an accurate documentation snapshot at month two and a steadily degrading reference thereafter. The open-source extractor surfaces these founding documentation platform sessions from AI chat history, because the session contains the evaluation criteria and trade-off reasoning that the documentation strategy decision record should preserve: why the team chose Notion over Confluence, why they chose a wiki over docs-as-code, what they were optimizing for at the team's current size. That reasoning is the context required to evaluate whether the documentation strategy is still correct when the team reaches thirty engineers, or whether the trade-offs that were correct for seven people have become the constraints that are slowing down twenty-three.

The runbook creation session is where the operational procedure is documented and the maintenance policy is implicitly deferred. When a team encounters a new class of operational failure — a database connection pool exhaustion, a cache eviction cascade, a message queue consumer lag spike — they write a runbook to capture the correct response. The AI session that produces the runbook is focused on the procedure: what are the diagnostic steps, what are the mitigation actions, what are the escalation paths. The session produces an accurate runbook at the time of writing. What the session does not produce is the maintenance specification: how frequently will this runbook be tested against a staging environment, who is responsible for the test, what is the trigger that updates the runbook when the underlying system changes, and how will anyone know when the runbook has drifted from the current system configuration? These questions are not urgent at the time the runbook is written, because the system and the runbook are synchronized. They become urgent at the moment the system changes without a corresponding runbook update — which is the normal state of an evolving production system. The incident response playbook decision record addresses the specific subset of runbooks that govern P0 incident response; the documentation strategy decision record must cover the full category, including routine operational procedures that are rarely exercised but critical when needed. Procedures that are rarely exercised are the ones most likely to be stale when executed, because the staleness has had more time to accumulate and the infrequency of execution means there is no regular signal that the procedure is outdated.

The API documentation strategy session is where the documentation format, platform, and initial owner are determined and the currency enforcement mechanism is not. The team evaluates OpenAPI specification, Postman collections, Readme.io, and wiki-based documentation, and selects a format appropriate for their current API surface. The session produces a clear answer to "how do we document our API?" What the session does not produce is the enforcement specification: what is the CI gate that prevents a deployed API change from diverging from the committed specification? What is the review requirement that includes documentation updates in the same PR as endpoint changes? What is the audit cadence that checks the documentation against the running API for teams using wiki-based documentation? Without these specifications, the documentation format and platform are choices without a policy — the team knows where the documentation lives but has no mechanism ensuring it stays current. The API versioning decision record is directly coupled to the API documentation strategy: a versioning model that requires explicit version namespacing creates a natural documentation checkpoint (the new version requires new documentation), while a versioning model that allows additive changes within a single version namespace requires a more active documentation monitoring policy to catch undocumented additions like the output_format=json case above.

The five sections of a documentation strategy decision record

The first section documents the documentation platform selection and the docs-as-code versus wiki decision rationale. This section answers the questions the founding AI session answered — which platforms were evaluated, which were selected, and why — but structures the answers in a form that is evaluatable by a future engineer who was not in the session. The platform selection rationale must be specific: "Notion was selected over Confluence because the team of seven already had personal Notion accounts and the migration cost to Confluence was estimated at two weeks of engineering time with no meaningful capability gain at current scale" is evaluatable. "We chose Notion because it's more flexible" is not. The docs-as-code decision must specify which documentation categories live in the code repository (API specifications, code-level documentation, ADRs) and which categories live in the wiki (runbooks, environment guides, team processes), with the rationale for each partition. The section must include the expected re-evaluation trigger: at what team size, system complexity, or documentation volume does the platform selection deserve to be revisited? For a team of seven choosing Notion, a reasonable trigger is "at 20 engineers or 50 documents, whichever comes first." Writing the re-evaluation trigger in the founding decision prevents the platform choice from becoming invisible debt — documentation strategy decisions are among the most difficult to change after they have been in place for two years, because the migration cost of existing documentation increases linearly with the documentation volume.

The second section documents the ownership model, assignment mechanism, and ownership transfer protocol. The ownership model must specify the unit of ownership (individual document, documentation area, system component) and the assignment mechanism (explicit metadata field in each document, a CODEOWNERS-style mapping file, an ownership registry in the documentation system's metadata). The assignment mechanism must be machine-readable if the documentation platform supports it — an ownership field that is searchable and filterable allows the team to ask "which documents does engineer X own?" at offboarding time, rather than requiring manual recall. The ownership transfer protocol specifies what happens when a document's owner leaves the company, changes roles, or hands off a system to a different team. At minimum, the offboarding checklist must include a documentation ownership review step: the departing engineer transfers each owned document to a named successor, and the successor reviews the document against the current system state before accepting ownership. The section must also document the policy for unowned documentation: what is the process for identifying orphaned documents, who is responsible for triaging them, and what is the policy for documents that have been orphaned long enough to be unreliable — archive, delete, or tag as unverified? The platform engineering documentation is the category where ownership gaps are most consequential, because platform teams frequently own documentation that is consumed by every product team in the organization. A gap in platform documentation affects not the platform team's productivity but the productivity of every team that uses the platform.

The third section documents the staleness detection mechanism and documentation currency policy. The staleness detection mechanism must be specified per documentation category, because different categories have different verification approaches. For API documentation in an OpenAPI specification: the CI pipeline generates the API spec from the running application (or validates the committed spec against the running application) and fails the build on any divergence. The CI job, the command that generates or validates the spec, and the expected output format must be documented here — not as implementation details, but as the structural commitment the team is making to documentation currency for this category. For runbooks: the testing cadence (quarterly dry-run for critical runbooks, annual for low-frequency procedures), the environment used for testing (staging, a dedicated runbook test environment, or a simulated environment), and the person responsible for scheduling and running the tests. For architecture documentation: the review trigger (annually, or after any significant system change that affects the documented architecture) and the reviewer. The documentation currency policy is the complement to the staleness detection mechanism: it defines what "current enough" means for each documentation category. A runbook that is three months old without a system change is current enough. A runbook that is three months old and the underlying system was migrated to Kubernetes two months ago is not current enough — but without a detection mechanism, both runbooks look identical in the documentation system. The policy defines the currency threshold; the detection mechanism produces the signal that a document has crossed that threshold.

The fourth section documents the canonical location policy and the undiscoverable surface control protocol. The canonical location policy specifies, for each type of information that engineering teams produce, exactly where that information must be stored and who is responsible for ensuring it reaches the canonical location. The policy must cover at minimum: API documentation (specification file in the code repository), runbooks (runbook system, with a named owner), architectural decisions (ADR directory in the relevant code repository), environment configuration (infrastructure-as-code repository, not in runbooks or wikis), and escalation paths (on-call documentation system, reviewed quarterly). The policy must explicitly address non-canonical locations: information documented in Slack, PR descriptions, meeting notes, or personal notes is not authoritative, and engineers who encounter important information in these locations are expected to migrate it to the canonical location before treating it as reliable. The undiscoverable surface control protocol specifies the periodic documentation audit: frequency, scope, reviewer, and output format. The audit is not a remediation exercise — it is a visibility exercise that produces a prioritized list of documentation gaps. Each audit produces a set of documentation debt tickets that are prioritized alongside feature work. Documentation debt that is not triaged and prioritized alongside feature work is documentation debt that will never be addressed, because it will always be deprioritized against user-facing deliverables. The audit cadence and the debt triage process are the organizational commitment that distinguishes a documentation strategy from a documentation aspiration.

The fifth section documents the API documentation contract enforcement gate and the runbook test cadence. This section converts the currency policies from section three into specific, operational commitments. For API documentation enforcement: the exact CI job name, the command that runs it, the conditions under which it is triggered (every PR, every merge to main, or every deployment), and the escalation path when the check fails (block the PR, block the deployment, or create a ticket and allow through). For runbook testing: the schedule of runbook dry-runs for the current quarter, the engineer assigned to each test, the staging environment URL, and the expected output (a completed checklist of runbook steps verified, a list of steps that require updates, and a PR or ticket created for each identified update). The section must also document the process for runbooks that cannot be tested in staging — procedures for production-only failure modes, disaster recovery procedures that require destructive actions to test, or procedures for systems that do not have a staging analog. For these runbooks, the documentation policy must specify an alternative verification method: peer review by an engineer with recent experience executing the procedure, a tabletop exercise that walks through the procedure without executing it, or explicit labeling as untested with a date of last review. Untested runbooks are not equivalent to tested runbooks, and the documentation system should make this distinction visible rather than treating all documents equally regardless of their verification status.

The documentation platform selection session, the runbook creation session, and the API documentation strategy session each produce documentation strategy decisions whose long-term cost — forty-seven minutes of P0 incident duration caused by stale runbook references, or enterprise customers building unnecessary workarounds around an undocumented API parameter — exceeds what a documentation currency policy would have cost at the time the decision was made. The decisions are in the AI chat history: the rationale for choosing Notion over Confluence, the post-incident update policy that seemed complete when it was designed, the API documentation ownership convention that worked for seven engineers. WhyChose's open-source extractor surfaces these founding documentation strategy sessions as structured records before the next on-call shift, the next integration customer, or the next engineer departure makes the undocumented assumptions visible as operational failures. The new CTO onboarding problem is also a documentation problem: an incoming technical leader will find runbooks whose last-edited dates do not reflect the underlying system's last-changed dates, API documentation whose valid parameter values do not match the running API, and no document explaining which documentation the team considers authoritative versus aspirational — because the decisions that produced those answers exist only in the AI sessions from the day the founding team chose their documentation platform and ownership model.