- Description
- Longue allée de rayonnages de magasin de bibliothèque, remplis de volumes reliés.
- Source
- Chevsapher · original page
- Licence
- CC0 Public domain
Documentation and Knowledge Transfer
This theme measures the team's resilience to someone leaving or joining: what is known by everyone, found in a few minutes, and kept up to date because documentation lives…
In brief
This theme measures the team's resilience to someone leaving or joining: what is known by everyone, found in a few minutes, and kept up to date because documentation lives with the code. The promise is not “lots of pages” but “a new joiner becomes productive quickly, and a departure does not create a gap.” For data-specific documentation (catalog, lineage), see Data 12.
Level: 🟢→🔴 · Theme code: DOC (DL matrix)
Why this theme#
The bus factor is the number of people whose departure would paralyze a component. When it is 1, everyone knows it, no one says it. Documentation does not replace oral knowledge transfer, but it makes it asynchronous, searchable, and durable. It also has an enemy: obsolescence. Incorrect documentation is worse than none, because it creates unjustified trust.
The Diátaxis framework distinguishes four types of documents that are often mixed up: tutorials (learning), how-to guides (completing a task), reference material (looking things up), explanations (understanding why). A single document cannot do everything at once. The most durable documentation is adjacent to the code and generated when possible (interface references, database schemas, SQL extended properties), to avoid drifting double entry.
What the theme measures#
- Axis: from “knowledge is in people's heads” to “knowledge is shared, verified, and used.”
- Key indicators: bus factor by component; time to autonomy for a new joiner; median page age; recurring question rate.
- Unit: number of people; days; months; %.
Five-level table#
| Level | Short name | Promise | Typical indicator (orders of magnitude) |
|---|---|---|---|
| 1 | Oral | Knowledge is available as long as people are available. | Bus factor = 1 on key components |
| 2 | Written | A new joiner finds enough to get started and knows whom to ask. | Home and setup pages; autonomy ≈ 4-8 weeks |
| 3 | Maintained | Documentation is found in under 5 minutes and its freshness is known. | Owner per page; obsolescence < 12 months |
| 4 | Living | Documentation is updated with code, and whatever can be generated is generated. | Checked in review; generated references; autonomy ≈ 2 weeks |
| 5 | Shared | Every component has at least three people able to evolve it, and knowledge flows without meetings. | Bus factor ≥ 3 everywhere; autonomy < 1 week |
Milestones by level#
| ID | Milestone | Verifiable evidence |
|---|---|---|
| DL-DOC-1.1 | A single entry point links to the rest (repository home, team page) | Link known by everyone |
| DL-DOC-1.2 | Setup and build procedures are documented | Followed by a third party: success |
| DL-DOC-1.3 | Experts for each component are identified | Component → people table |
| DL-DOC-2.1 | An onboarding guide lists access, tools, and first tasks | Used by the last 3 arrivals |
| DL-DOC-2.2 | The architecture is described at a high level (see 01) | Dated diagram |
| DL-DOC-2.3 | Interfaces (API, views, file exchanges) have reference documentation | Browsable reference |
| DL-DOC-2.4 | Operations procedures (start, resume, restore) are documented | Replayed once by a non-author |
| DL-DOC-3.1 | Each page shows an owner and last review date | Metadata present on ≥ 90% |
| DL-DOC-3.2 | A search engine covers the documentation; FAQs are tracked | Test: 5 questions found in < 5 min |
| DL-DOC-3.3 | The four types (tutorial, guide, reference, explanation) are distinguished | Site structure |
| DL-DOC-3.4 | Important decisions are kept with their context (ADR) | Decision log |
| DL-DOC-3.5 | Bus factor is assessed by component and tracked | Table updated quarterly |
| DL-DOC-4.1 | Documentation is in the repository, versioned with the code, and reviewed in the same merge request | Review of 10 PRs: docs updated when needed |
| DL-DOC-4.2 | References (schemas, API, SQL properties) are generated from source | Pipeline generation |
| DL-DOC-4.3 | Documentation links and code examples are automatically tested | CI check |
| DL-DOC-4.4 | Documentation is published with each release and matching version | Site per version |
| DL-DOC-4.5 | Time to autonomy for a new joiner is measured and < 2-3 weeks | Measured on the last 3 arrivals |
| DL-DOC-5.1 | Bus factor ≥ 3 on each critical component | Skills matrix |
| DL-DOC-5.2 | Regular transfer practices (pairing, rotations, cross-reviews) are institutionalized | Schedule and records |
| DL-DOC-5.3 | A simulated departure (exercise “what if X left?”) reveals no critical gap | Exercise report |
| DL-DOC-5.4 | Recurring questions become documentation or automation in < 1 month | Recurring question tracking |
Detailed reading by level#
🟢 Level 1 — Oral#
- Signs: “ask so-and-so”; ghost setup; conflicting answers.
- Gain: zero writing cost.
- Does not guarantee: continuity if an expert leaves or gets sick.
- Difficulty: 1/5 · Effort: 1/5.
🟢 Level 2 — Written#
- Signs: an onboarding guide, a diagram, operations procedures.
- Gain: initial autonomy for new joiners.
- Does not guarantee: freshness; most documentation at this level becomes obsolete within a year.
- Difficulty: 2/5 · Effort: 2/5.
🟡 Level 3 — Maintained#
- Signs: each page has an owner and review date; search works; the why (decisions) is preserved alongside the how.
- Gain: people trust documentation, so they consult it, so they correct it.
- Does not guarantee: that it keeps pace with the code.
- Difficulty: 3/5 · Effort: 3/5.
🔴 Level 4 — Living#
- Signs: “docs are part of the definition of done”; review rejects an interface change without a reference update; whatever can be derived from code or database (schemas, dictionary, extended properties) is generated.
- Gain: freshness becomes a side effect of day-to-day work.
- Does not guarantee: tacit transfer (judgment, business intuition).
- Difficulty: 4/5 · Effort: 4/5.
🔴 Level 5 — Shared#
- Signs: rotations, pairing, cross-reviews; bus factor is ≥ 3; a simulated departure exercise finds no gap.
- Gain: organizational resilience.
- Does not guarantee: efficiency — too much skill redundancy has a cost, to be calibrated to criticality.
- Difficulty: 5/5 · Effort: 4/5.
Partial achievement and rating#
Apply the rating rule.
- 0.5 on DL-DOC-4.2: references generated for the database, hand-written for APIs.
- 0.5 on DL-DOC-5.1: bus factor ≥ 3 on half of critical components.
- A partial 5: real annual rotations but no simulated departure exercise.
Graveyard wiki. Symptom: 600 pages, 80% obsolete, no one knows which ones. Cause: no ownership or date. Fix: archive anything without an owner; mark the review date.
Single-type documentation. Symptom: one 40-screen page that tries to be everything at once. Cause: tutorial/guide/reference/explanation distinction is ignored. Fix: split it.
The best documentation test: have someone who has never seen the component perform a real task (install, deploy a fix) without help. Every question is a documentation defect.
Summarizing, drafting a first version, answering questions from the documentation base: gain 4/5, risk 3/5 (plausible but obsolete or made-up answers). Safeguard: AI cites its internal sources and publishes nothing without owner review.
Measuring page count produces volume; measure time to autonomy and freshness.
Moving to the next level#
Possible means (optional)
- 1 → 2: an onboarding guide written by the last person who joined (they are the one who knows the gaps).
- 2 → 3: owner and date per page, archiving, ADR.
- 3 → 4: documentation in the repository, generated references, link checks.
- 4 → 5: rotations, simulated departure exercise, skills matrix.
See also#
- Neighbors: 01 Architecture · 09 Technical Debt · 12 Developer Experience · 06 Deployment.
- Other matrices: Data — Metadata, Lineage, and Documentation · Project — Team and Collaboration · Project — Continuous Improvement and Learning.
- Practice: Git In Depth · AI and Tools · Project Management Fundamentals.
- Glossary · Rating.
✻ Written by Claude Sonnet 5.5
