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.
What is an assumption log, and what makes an entry in one actually useful? How is it different from a risk log or a decision log, and when do you update it?
Sample Answer
Direct answer
An assumption log is a living list of the things a project is treating as true without having proved them. A useful entry is specific, falsifiable (written so a test could prove it wrong), owned, backed by stated evidence, and has a date by which it must be validated or dropped. It differs from a risk log (possible future events) and a decision log (choices already made). You update it continuously, in the routines the team already runs, and at every milestone.
Structured elaboration
What makes an entry useful
- Statement: concrete and testable. Bad: "users want reports". Good: "at least half of active admins export a report weekly".
- Owner: the one person who will chase the answer.
- Evidence and confidence: what we know now (source, sample size) and how sure we are (high / medium / low).
- Impact if wrong: what breaks, so we test the expensive ones first. For a data analyst: "if exports are not CSV, the ingestion script must be rewritten, about two weeks of rework". For a business analyst: "if the sponsor has not approved the budget, the scope in the requirements document is void".
- Validation method and date (expiry): how we will test it and when it must be settled. An untested assumption without a date is just an opinion.
- Status: open, validated, invalidated, retired. Plus a link to the decisions that depend on it.
How it differs from a risk log and a decision log
| Log | What it holds | Shape of an entry | Question it answers |
|---|---|---|---|
| Assumption log | Beliefs treated as true | Statement, evidence, validate-by date | "What are we relying on?" |
| Risk log | Possible bad future events | Event, probability, impact, mitigation | "What could go wrong?" |
| Decision log | Choices made and why | Decision, options, rationale | "What did we choose?" |
They connect: an assumption is an input to a decision, and an invalidated assumption usually becomes a risk or an issue.
When to update
- In daily scrum (the short daily team check-in), ask one question: did anything block or change an assumption?
- In sprint planning (the meeting where the team picks the work for the next one to two weeks), scan open assumptions and pull validation work in as tickets.
- When new evidence arrives, and at milestones (agreed checkpoints such as "design approved") or phase gates (formal go/no-go reviews between project stages). Surfacing it through the project lifecycle reduces ambiguity, because people stop building on unstated beliefs.
- On the expiry date, when the owner must validate, extend with a reason, or invalidate.
After a discovery call (an early meeting with a customer or stakeholder to learn their needs)
Capture assumptions and open questions the same day. For each, assign an owner (the person best placed to find the answer, not the note taker) and a date. Flag any item that touches contracts, data privacy or regulation for legal review, and any item that would change scope for escalation to the sponsor (the executive who funds the project and must approve scope changes). Example: "the customer assumes we will migrate 10 years of history" is escalated because it could double the effort.
Worked example
| ID | Statement | Owner | Evidence, confidence | Validate by | Status |
|---|---|---|---|---|---|
| A1 | Customer exports arrive as CSV, under 100 MB | Priya | One sample file, low | 10 Oct | open |
| A2 | Legal permits storing EU data in the US region | Legal contact | None yet, low. Flag: legal review | 8 Oct | open |
| A3 | Payments API supports refunds by order ID | Sam | Read API docs, high | 3 Oct | validated |
If A1 is invalidated (a customer sends 2 GB files), it becomes a risk entry ("upload pipeline may fail on large files") and triggers a decision record about chunked uploads.
Trade-offs and pitfalls
- Vague entries ("system will be fast") cannot be tested. Rewrite until a test exists.
- Logs die when nobody owns them: name one owner for the log itself and review it in planning.
- Do not merge it into the risk log. Mixing them loses the "how do we validate this?" discipline.
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.
Your team holds too many recurring sync meetings just to keep stakeholders informed about model development. Propose an asynchronous documentation approach that replaces most of them while keeping people accountable: what documents exist, who owns them, how often they are updated, and how people find them.
Sample Answer
Direct answer
Replace status meetings with a small set of living documents, each with one named owner, a fixed update rhythm, and one index page that everyone bookmarks. Meetings that remain are for decisions, not for reading out updates. Accountability comes from ownership and from visible staleness ("last updated" dates and an automatic nudge), not from having people talk.
The documents (worked example for a model-development team)
| Document | Owner | Update cadence | Audience and purpose |
|---|---|---|---|
| Project brief | Product manager (PM) | Once, revised on scope change | Goal, success metric, non-goals (things deliberately out of scope), stakeholders |
| Weekly status note | Tech lead | Every Friday, 5 bullets max | Done, next, blocked, risks, decisions needed |
| Experiment log | Each ML engineer or data scientist | After each experiment | Hypothesis, data version, result vs baseline, next step |
| Model card | Model owner | On each release candidate | A short standard document: what the model is for, training data, evaluation results, known limits |
| Decision log | Tech lead | When a decision is made | What was decided, options, who, date |
| Risks and dependencies board | PM | Weekly review | A simple list of what could go wrong and which other teams' work we are waiting on, with an owner for each |
An example experiment log entry (so the fields are concrete):
Experiment #41 | Owner: S. Patel | 2026-09-16
Hypothesis: adding last-30-day support tickets as a feature will improve churn prediction
Data version: customers_2026_08 (the frozen snapshot used for training)
Result vs baseline: score 0.82 vs 0.80 for the current production model
Next step: test on live traffic
An example weekly note:
Week of 2026-09-21: churn model v3
Done: retrained on Aug data; offline metric vs baseline: +0.02 (see experiment #41)
Next: shadow test against live traffic
Blocked: feature table refresh owned by Data Eng (needs answer by Wed)
Decision needed: ship threshold 0.4 or 0.5? (PM, by Fri, options in decision log #12)
Plain-language reading for a non-ML stakeholder: the offline metric is the model's score on saved historical data, and +0.02 means it beats the current model by two points (for example 0.80 to 0.82). A shadow test runs the new model quietly next to the live one on real traffic, without affecting customers, to check it behaves. The ship threshold is the score cutoff above which a customer is flagged as likely to churn: 0.4 flags more customers (more catches, more false alarms), 0.5 flags fewer.
Who owns what, and how people find it
- One index page per project links every document above, and each doc header carries owner, last-updated date and status. The index is linked from the team channel topic.
- Stakeholders subscribe to page changes or a weekly digest, so information reaches them without a meeting.
- Naming and location are fixed by a template, so nobody hunts.
Keeping people accountable without meetings
- Comments and questions are answered in the doc thread within an agreed window (for example one business day), and unanswered questions surface in the weekly note.
- A stale doc (not updated within twice its cadence) is flagged automatically to its owner and their manager.
- A 25-minute fortnightly decision review replaces several syncs: only items in the "decision needed" section are discussed.
Trade-offs and pitfalls
- Async docs fail when nobody reads them; ask stakeholders which fields they need, and cut the rest.
- Sensitive or ambiguous topics (a missed target, a conflict) still deserve a live conversation; write-ups can hide disagreement.
- Cutting meetings all at once breaks trust. Pilot for a month, drop the sync that has the lowest attendance value first, and compare stakeholder questions asked in ad hoc messages before and after.
- What would flip it: if stakeholders keep asking the same questions in chat, the docs are not answering what they need, so revise the docs rather than restoring the meeting.
A cross-functional initiative just wrapped and everyone agrees the lessons are valuable, but past experience says they will be filed and forgotten. How would you capture them in a way that future teams actually find and use, and how would you check they changed anything?
Sample Answer
Direct answer
Lessons are forgotten because they are captured as a report and nobody has a reason to open it. I would capture a few specific, actionable lessons, attach each to the moment in a future project where it applies, convert the best ones into changes in templates, checklists or automation (so people use them without reading anything), and then check three things: were they found, were they applied, and did the same problem recur.
Structured elaboration
1. Capture: fewer, sharper, owned
- Hold the review within two weeks of wrap-up while memory is fresh, with people from every function that took part. Keep it blameless (focus on how the process allowed the problem, not who caused it).
- Distil to 5-8 lessons. Each lesson uses one card: context (what was going on), what happened, what to do next time in a concrete verb form, and the trigger ("when planning a vendor integration...").
- Each lesson has a named owner who is responsible for turning it into a change. A lesson without an owner is a wish.
2. Make them findable at the point of use
- Tag by the decision point or project phase the lesson affects (kickoff, vendor selection, launch readiness), not just by project name. People search by their current problem, not by the last project's title.
- Store in one place that the kickoff process itself points to: the project kickoff template includes a mandatory step, "review lessons tagged for this phase and list which apply".
- Push, do not just pull: a short summary goes to the owners of the next planned initiatives.
3. Convert lessons into changes
A lesson that only lives in a document depends on memory. Prefer, in order: an automated check or default, a checklist or template line, a named role or gate, and only last a document.
4. Check they changed anything
- Found: were lesson cards opened or cited at the next kickoffs (link clicks, or the kickoff template's "lessons reviewed" field filled in)?
- Applied: for each converted lesson, did the next initiative actually do the new step (audit two projects at 90 days)?
- Outcome: did the original problem recur? Track recurrence per lesson (yes, no, partly). Be honest that with a couple of projects this is evidence, not proof.
Worked example
A billing-migration initiative finished. One lesson: legal review of the new vendor contract began after the contract was drafted, which stalled launch for several weeks.
Lesson L3
Context: New payments vendor, contract drafted by procurement.
Happened: Legal saw the data-processing terms only after vendor selection, forcing renegotiation.
Next time: Start legal review at vendor shortlisting, before any pricing talks.
Trigger: Any project that adds a third party who will handle customer data.
Owner: Program manager for platform initiatives
Change: Add "Legal review started (date)" as a line in the vendor-selection checklist.
Check: At 90 days, did the next two vendor projects show that date before contract draft?
Suppose the audit finds one of the next two projects started legal review early and one did not. That is 1 of 2 applied: the owner asks why the second missed it (checklist not known to that team), and fixes the distribution, not the people.
Trade-offs and pitfalls
- A long retrospective document is comprehensive and unread. Prefer the card format.
- Generic lessons ("communicate earlier") cannot be applied. Force a trigger and a verb.
- Blame-shaped lessons make people hide problems next time.
- Recommend investing in checklist and template changes over a searchable archive, because the archive still depends on someone thinking to search. What would change my call: for a rare, one-off initiative that will never repeat, a short written note to the sponsor is enough.
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.
Unlock Full Question Bank
Get access to all 13 Documentation and Knowledge Management interview questions and detailed answers.
Sign in to ContinueJoin thousands of developers preparing for their dream job.