Documentation and Knowledge Management Questions
Governing how teams capture and keep knowledge usable: documentation standards, ownership models (centralized, federated or dedicated team) and review cadences, incentives and culture change that get engineers to document, decision records and assumption logs, post-project reviews that preserve lessons, and knowledge-base strategy so organizational knowledge stays findable and attributed. Includes building or buying a knowledge platform, migration and consolidation plans, taxonomy, tagging and search quality, linking docs to code, capturing tacit expertise into the knowledge base, detecting and remediating stale docs across a documentation estate, and versioning and change policies for shared reports and metric definitions. Covers the governance and lifecycle of a body of documentation, not the craft of writing any single document.
Should a mid-sized engineering organization keep a dedicated documentation team or have each engineering team own its own docs? Weigh accuracy, findability, speed of updates, consistency and onboarding, and recommend a model with the conditions under which you would change it.
Sample Answer
Direct answer
For a mid-sized engineering organization (roughly 50 to 300 engineers), I recommend that each engineering team owns the content of its own docs, supported by a small enablement function (one to three technical writers or a docs-minded engineer) that owns templates, tooling, and editing of the highest-visibility material. A fully dedicated documentation team writing everything is too slow and too far from the code at this size; a pure "everyone for themselves" model produces inconsistency and poor findability.
Weighing the criteria
| Criterion | Dedicated team writes it | Teams own their docs |
|---|---|---|
| Accuracy | Lags: writers depend on engineers for facts | Best: the author made the change |
| Findability | Strong: one structure | Weak without shared structure and search |
| Speed of updates | Slow: request and queue | Fast: same pull request as the code |
| Consistency | Strong | Weak without templates and checks |
| Onboarding | Polished getting-started paths | Uneven, depends on the team |
The criteria split: the dedicated model wins consistency, findability and onboarding polish; team ownership wins accuracy and speed. The hybrid captures most of both by having the enablement function fix the weak columns (templates, shared search, onboarding curriculum) while teams keep speed and accuracy.
Terms
- Findability: how quickly a person can locate the doc they need.
- Enablement function: a small group that helps other teams do something well (here, writing docs) instead of doing it for them.
- Definition of done: the checklist a piece of work must satisfy before it counts as finished.
Worked example
An organization with 120 engineers in 15 teams. Suppose docs requests to a central team average a two-week wait, and a doc is stale within a release. Under the hybrid, teams update docs in the same pull request as the change (so the wait is zero), and two enablement staff spend their time on: the template and style guide, an onboarding path, editing the 10 documents new customers and new hires read first, and a quarterly audit of stale docs. That is 2 people supporting 120, instead of 2 people trying to write for 120.
To know the model is working, measure before and after (the numbers below are illustrative targets, not results):
Measure Baseline Target after 2 quarters
Doc update wait 14 days 0 (same pull request)
New hire to first merged change 20 days 12 days
Docs past their review date 40% 15%
If a target is missed, that is the signal for the "conditions to change" below.
Conditions under which I would change the model
- Toward a dedicated team: the docs are a product itself (public developer docs, regulated documentation with legal review), quality is judged externally, or engineers repeatedly write poorly despite templates.
- Toward pure team ownership: the organization shrinks or docs are internal only and the enablement function has become a bottleneck.
- Toward more central support: onboarding time keeps rising, or the share of docs with no owner or past review date exceeds an agreed limit.
Pitfalls
- Team ownership without time budgeted for writing means docs never get written. Include documentation in the definition of done (a doc update is required before a change counts as finished).
- A dedicated team without a link to code teams writes accurate-looking but wrong docs.
- Measuring only output volume rewards padding; measure onboarding time and repeat questions.
You are moving scattered documentation into one centralized knowledge base. Lay out your migration plan from first inventory to cutover: how you decide what to keep, merge or retire, how content gets owners and stays findable, what happens to old material, and which measures tell you the migration worked.
Sample Answer
Direct answer
Treat the migration as content curation first, tooling second: inventory everything, decide keep, merge or retire using a simple scoring rule, put owners and metadata on every kept page BEFORE moving it, migrate in waves ordered by operational criticality, leave redirects behind, and judge success by whether people find answers faster, not by how many pages moved.
Terms
- Inventory: a spreadsheet listing every doc, where it lives, who wrote it and when it last changed.
- Redirect: an old link that automatically forwards to the new location.
- Cutover: the moment the new system becomes the official source.
- Runbook: step-by-step instructions for operating or fixing a system.
Phase 1: Inventory and triage (weeks 1-2)
Crawl the wikis, shared drives and repos, and add the informal sources: chat channels and personal notes. Record for each item: location, owner, last edit, views if known, and which system it describes.
Decide keep, merge or retire with a short rule:
| Decision | Rule |
|---|---|
| Keep | Still accurate, describes a live system, and is used or operationally needed |
| Merge | Overlaps another page on the same topic; combine into one canonical page |
| Retire | Describes decommissioned systems, unedited for a long time, and nobody uses it |
| Ask a domain owner to confirm every retire in bulk, so nothing critical vanishes silently. |
Worked example (illustrative arithmetic)
Inventory finds 400 items. Triage results: 120 keep, 90 merge (they collapse into 30 pages), 190 retire. The new knowledge base receives 120 + 30 = 150 pages, 37.5 percent of the original. Every item still has a recorded fate in the inventory, so the numbers reconcile: 120 + 90 + 190 = 400.
Phase 2: Structure, ownership, findability
- Target structure: a few top-level areas (for example Services, Runbooks, Processes, Onboarding), not a mirror of the org chart.
- Tags: a small controlled list (team, system, lifecycle, audience); no free-form tags at launch.
- Every page has an owner team and a last-reviewed date; pages without an owner are not migrated.
- Search: index titles, headings and tags, boost pages by verified freshness, and test with a list of the 20 most common real questions.
Phase 3: Migrate in waves, by operational criticality
For knowledge that lives only in chat channels and personal notes, rank by "what hurts if it is missing at 3am": on-call runbooks and recovery steps first, then setup and onboarding, then background context. Capture chat knowledge by turning a decision or fix into a proper page (with the thread linked), not by dumping the export. Set a measurable onboarding-speed goal, for example that a new engineer completes the first supervised on-call shift using only the knowledge base, and measure the median days before and after.
Phase 4: Old material and cutover
Freeze the old wikis to read-only with a banner pointing to the new location, keep redirects for a defined period, archive (do not delete) retired items for legal or historical reasons, then switch off after traffic to old links falls.
Success measures
- Search: share of searches with a click and no immediate re-search, and zero-result queries falling.
- Coverage: percent of critical systems with an owned, current runbook.
- Freshness: percent of pages reviewed within their window.
- Onboarding speed (above) and fewer "where is the doc for X" questions in chat.
Trade-offs and pitfalls
- Migrating everything "just in case" copies the rot into the new home.
- No owners means the new system decays as the old one did.
- A big-bang cutover is riskier than waves, but waves prolong two sources of truth, so set a firm end date.
- What would change my call: a small team with 50 pages should skip scoring and simply re-read them.
Your organization is growing fast and new hires take too long to become productive, while senior engineers are constantly interrupted with questions. How would you scale documentation and knowledge capture so ramp-up speeds up without adding load on seniors?
Sample Answer
Direct answer
Treat the interruptions as data. Log what new hires ask seniors for two weeks, write the docs for the questions that repeat, route every future question through "answer in the doc, then link it", and build a structured first-30-days path. Bound the remaining interruptions with office hours and a buddy rotation so seniors are asked on a schedule instead of continuously. Write only what gets asked twice, otherwise the docs become a second job nobody has time for.
Terms
- Runbook: step-by-step instructions for an operational task, such as deploying or restarting a service.
- README: the front-page file of a code repository that explains what it is and how to run it.
- Stub: a short placeholder page with a title and a link, to be filled in later.
- Shelfware: documentation written once, never used, and left to rot.
- Buddy rotation: a schedule assigning a different teammate each week as the person a new hire asks first.
- Office hours: fixed times when seniors are available for questions, so they are not interrupted at other times.
- Single-point-of-knowledge risk: only one person understands something, so their absence stops the team.
- Time to first merged change: days from a new hire's start until their first change is accepted into the shared code or content.
Step 1: Measure the question stream (weeks 1-2)
Ask new hires to drop every question they take to a senior into one tracker (a channel or form) with a topic tag. Suppose 40 questions arrive in two weeks and they cluster like this:
| Topic | Count |
|---|---|
| Local environment setup | 9 |
| Deploy and release process | 6 |
| Which service owns what | 5 |
| Getting access and permissions | 3 |
| How to read our alerts | 3 |
| Everything else (one-offs) | 14 |
The top five topics account for 26 of 40 questions, which is 65 percent. Five good pages remove most of the repeat load. That is where to start, and it also tells you which pages to leave unwritten.
Step 2: Capture as a by-product of work
- Answer once, in the doc. When a senior answers a repeat question, they paste the answer into the page (or the new hire does) and reply with the link. The cost is two minutes and it is paid once.
- New hires write the setup guide. They have fresh eyes and find the gaps; a senior only reviews. The page is marked "last verified by (name), (date)".
- Definition of done includes docs. The pull request (PR) template asks "does this change how someone runs, deploys or debugs this service? Update the README or runbook."
- Short recorded walk-throughs for architecture, always with a written summary above the video, because video alone is not searchable.
Step 3: Structure the ramp-up
A checklist for day 1, week 1 and day 30 with links to the pages above and a first small task (a safe first pull request in week one). A filled-in version:
Day 1: accounts requested; join team channel; meet your buddy
Week 1: run the service locally (setup page); read "Which service owns what";
make one small safe change (fix a wrong line in a doc) and get it merged
Day 30: shadow one deploy; shadow one on-call shift; write or fix one page you found unclear
The measure of success is a new hire's time to first merged change, plus questions per new hire trending down.
Step 4: Protect seniors without going silent
- Two weekly office-hour slots and a rotating "ask first" buddy (not always the same senior).
- Rule for the team channel: search the docs, then ask; the answerer links the page, and if none exists, creates a stub.
Variant: a business intelligence (BI) team with single-point-of-knowledge risk
A BI team often has one analyst who alone understands a dashboard's logic. The same idea applies with a specific structure:
- Content structure: a metric dictionary page per metric (definition, source tables, refresh schedule, known caveats) and a page per dashboard (purpose, audience, inputs).
- Example metric dictionary entry (weekly active users):
Metric: Weekly active users (WAU)
Definition: distinct user IDs with at least one login or project action in the last 7 days (UTC)
Source: events.user_activity, excluding internal test accounts
Refresh: daily at 06:00 UTC
Owner/backup: A. Analyst / B. Analyst
Caveats: API-only usage not counted; definition changed 2026-03-01, earlier values not comparable
- Ownership: every page has a named owner and a named backup owner, so no page has one person only.
- Metadata: owner, backup, last-verified date, data source, refresh cadence, audience. This makes stale or orphaned pages queryable.
- Maintenance cadence: a quarterly review where each owner re-verifies their pages, plus a trigger whenever a source table changes.
Trade-offs and pitfalls
- Writing "complete" documentation up front produces shelfware. Demand-driven docs are smaller and used.
- If seniors are also the reviewers of every doc, you moved the load, not removed it. Let the second-most-experienced person review.
- Pages with no owner and no verified date go stale in a few months. Ownership is the design, not a nice-to-have.
- What would change my call: for a very small team (under about five people), pairing and a short README beat any portal.
You lead a team where documentation is poor and engineers resist writing it. Propose a multi-quarter plan to change the documentation culture. What do you do first, how do you handle cross-team governance, and how do you show progress each quarter?
Sample Answer
Direct answer
Do not start with a mandate or a big tool migration. Spend the first quarter finding out why engineers do not write docs (usually: no time, no clear owner, docs nobody reads, and no credit), fix the cheapest of those causes, and prove value on one high-pain area. Then add ownership and light governance in quarters two and three, and report progress with a small set of outcome metrics, not page counts.
Quarter 1: diagnose, then win one thing
- Interview 8-10 engineers across teams and read the last few months of onboarding questions and repeated Slack questions. Group them: "could not find it", "found it but wrong", "does not exist".
- Pick ONE painful area (typically on-call runbooks or service onboarding) and make it good, with the team's leads. A visible win before any policy is what buys credibility.
- Lower the cost of writing: a short template, docs stored next to code, and writing time budgeted in sprint planning as real capacity (meaning the team plans fewer feature points so writing is not unpaid overtime). A filled-in template for a service runbook is only four lines:
Purpose: Restart and drain the invoice worker when the queue backs up
Owner: payments team (#payments-oncall)
How to operate: 1) check queue depth on the dashboard 2) run the drain command 3) confirm depth falls
Known failure modes: drain hangs if the database is read-only; escalate to the database team
- Record a baseline: median time for a new hire to make a first merged change, and the count of repeat questions in the help channel. For example, the baseline might be 21 days and 30 repeat questions a month (illustrative), so later quarters have something to be compared against.
Quarter 2: ownership and governance across teams
- Every doc has an owning team (a field in the doc header plus a CODEOWNERS file, a repository file naming who must review changes in a path). No owner means it is archived after a notice period.
- A lightweight cross-team docs guild (a group with one rep per team, meeting monthly) owns the template, the style guide and the definition of "done" (the team's checklist of what must be true before a piece of work counts as finished). Teams keep autonomy on content; the guild owns only standards. This is a hybrid between central control and free-for-all.
- Add CI checks (automated checks on each pull request): broken links, missing owner, doc past its review date. Warn first, block later.
- Make docs part of the "definition of done" (the checklist a piece of work must satisfy before it counts as finished) for new services and for changes to public interfaces, and reflect it in review, not in a separate approval board.
Quarter 3: reinforce and scale
- Recognition: docs work counts in promotion and performance packets (the written evidence engineers submit when they are reviewed for a raise or promotion), and a short "doc of the month" is shared. Incentives beat exhortation.
- Onboarding curriculum: a 30-day reading path made of the docs that exist, where the new hire files an issue for each gap, and fixing it is their first contribution.
- Retire or merge stale docs so trust in what remains rises.
How to show progress each quarter (worked example)
A leading indicator is an early signal of behavior you control (services with owners); an outcome indicator is the result you actually want (faster onboarding), which moves later.
| Quarter | Leading indicator | Outcome indicator |
|---|---|---|
| 1 | Baseline recorded (for example 21 days to first accepted pull request, 30 repeat questions a month); pain area chosen | Repeat questions in that area (count) |
| 2 | Share of services with an owner, for example 40 of 50 = 80% | Docs past review date, falling |
| 3 | Share of new services shipped with a runbook | New-hire time to first merged change vs the Q1 baseline (for example 21 days down to 14, a one-third drop; illustrative) |
Report the trend against the baseline, and never celebrate volume (pages written), because it rewards padding.
ML organization variant (reproducibility as the goal)
In a machine learning (ML) team, the doc that matters most is whatever lets someone else reproduce a result. Replace the generic template with: a model card (a short standard doc stating what a model is for, its training data, evaluation results and known limits), the exact dataset version, code commit, random seed (the fixed number that makes random steps in training repeat identically) and environment, and the metrics table. A minimal model card reads: "Purpose: rank support tickets by urgency. Training data: tickets Jan to Jun, dataset v4. Evaluation: 0.82 accuracy on held-out tickets (illustrative). Limits: not tested on non-English tickets." CI checks verify the card exists and its links to data and code resolve before a model can be promoted. Ownership is per model, and the curriculum includes re-running one past experiment from docs alone; failure to reproduce it is a documentation bug to fix. Quality over time is measured by the share of promoted models whose results a second person reproduced from the docs.
Pitfalls
- Mandating with no time budget produces low-quality docs and resentment.
- Central review boards become bottlenecks; keep standards central and content federated.
- Measuring page counts, or reading only engagement, hides whether docs are trusted.
- What would change the plan: if the survey shows the problem is findability, not absence, invest in search and structure before asking anyone to write more.
In a large engineering organization, compare a centralized documentation model with a federated one. How do ownership, findability, governance overhead, update speed and standards enforcement differ, when is each appropriate, and what hybrid would you propose?
Sample Answer
Direct answer
A centralized model puts one team in charge of writing, structure and tooling. A federated model lets each engineering team own its docs under shared standards. In a large organization neither extreme works alone, so I would recommend a hybrid: central ownership of the platform, standards and navigation; federated ownership of content, with each doc having an accountable owning team.
Comparison
| Dimension | Centralized | Federated |
|---|---|---|
| Ownership | Clear (doc team), but far from the code | Clear per team, but uneven across teams |
| Findability | High: one structure, one search | Low unless indexed: many styles, locations |
| Governance overhead | High: intake queue, review | Lower per team, but coordination cost across teams |
| Update speed | Slow: writers wait on engineers | Fast: authors are the people making the change |
| Standards enforcement | Easy: one gatekeeper | Hard: needs automation and peer pressure |
| Accuracy | Prone to lag and errors | Better where teams care; poor where they do not |
When each fits
- Centralized: a small organization, highly regulated or customer-facing docs where consistency and legal review matter, or a young platform where standards do not exist yet.
- Federated: many teams with different stacks, fast-moving internal engineering docs, and a culture where teams already own services end to end.
The hybrid I would propose (worked example)
Imagine 40 teams:
- A small platform team (2 to 4 people) owns the publishing tool, the templates, the style guide, the global search and the navigation. It does not write team content.
- Each team owns its docs in its own repository, marked with an owner in the doc header; a CODEOWNERS file (a repository file naming who must review changes in a path) makes this enforceable.
- Automated checks in CI (automated checks that run on each change) enforce standards: required sections, broken links, owner present, review date. This replaces a human gatekeeper.
- Tier-1 material (the small set of docs where an error is costly, such as public API, incident runbooks, security policies) gets extra editorial review from a small docs guild (one representative per team).
- All content is indexed into one search, and the platform team publishes a scorecard per team (share of docs with owner, share past review date), which makes uneven quality visible without policing. An illustrative scorecard:
Team Docs with owner Past review date
Payments 38 of 40 (95%) 3 of 40 (8%)
Search 20 of 25 (80%) 9 of 25 (36%)
Mobile 9 of 30 (30%) 18 of 30 (60%)
Mobile is the team to help first, not to shame.
Pitfalls
- Federated with no platform team ends in 40 different structures and no findability.
- Centralized with too few writers turns into a backlog; engineers route around it.
- A scorecard that punishes low scores encourages gaming; pair it with support for teams that are behind.
What would change my recommendation
If most docs are customer-facing and legally reviewed, lean central. If the organization is under roughly ten teams, a shared repo with light standards may be enough and the platform team can be part-time.
Unlock Full Question Bank
Get access to all 21 Documentation and Knowledge Management interview questions and detailed answers.
Sign in to ContinueJoin thousands of developers preparing for their dream job.