Documentation and Knowledge Management Questions

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

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.

Direct answer

Pay for outcomes that readers experience (docs that get used, kept current and that reduce questions), not for volume. I would build a small program with three parts: visible recognition and career credit rather than cash, a quality signal that comes from readers and from freshness, and guardrails against gaming. Then pilot it with two or three teams for a quarter before scaling.

Terms

• Gaming: producing what the metric rewards without the value it was meant to stand for (for example, splitting one page into ten).
• Docs-as-code: writing docs as files in the code repository, reviewed like code.
• Stale doc: one whose owner has not confirmed it is correct within an agreed period.
• Pilot: a limited trial with a comparison baseline.
• README: the front-page file of a code repository that says what it is and how to run it.
• Swag: small branded goodies such as t-shirts or stickers.
• Freshness: whether the doc has been confirmed correct recently (for example within 90 days).
• Extrinsic rewards crowd out pride: paying or prizing people for something they would otherwise do because they care can make them care less, so the reward replaces the pride instead of adding to it.

Why people do not write docs today (diagnose first)
Usually it is not laziness: writing is invisible in reviews, there is no time budgeted, docs rot so writing feels wasted, and the payoff goes to someone else. An incentive on top of a broken environment fails, so the program pairs incentives with removing friction (templates, docs in the repo, docs time in sprint planning).

Incentives (ranked by what I would try first)

1. Career credit: documentation impact counts in promotion and performance write-ups, with managers trained to ask about it.
2. Recognition: a monthly "most useful doc" chosen by readers, plus named owners on high-traffic pages.
3. Protected time: a small documentation allowance per sprint.
4. Small rewards (swag, conference budget) as a garnish. Avoid cash per page.

Judging quality without counting words

Worked check on one page: last confirmed 2026-07-01, so on 2026-09-28 it is 89 days old and passes the 90-day rule. A page confirmed 2026-06-20 is 100 days old and is flagged stale. The first page has 14 helpful votes from 5 different teams and a peer score of 5 of 6, so it is a strong result. A page with 14 votes all from the author's own team and a peer score of 2 of 6 is not, however popular it looks.

Anti-gaming guardrails

• Never reward raw count or length.
• Credit revisions and deletions of duplicates as much as new pages.
• Rate limits on credited edits per person and per page, and a minimum age before the same page earns credit again.
• Publish the rules so gaming is visible, and review outliers by hand.

Pilot design
Pick two teams that volunteer plus one comparison team without the program. Baselines before start: share of services with a current README, and median time for a new hire to make a first change (measure, don't guess). Run for one quarter, then interview participants and read the sampled docs. Success means participants' freshness and reader ratings rise versus the comparison team without a jump in trivial pages. Illustrative numbers: at baseline 6 of 20 services (30 percent) have a current README and a new hire's median time to a first change is 12 days. After a quarter, the pilot teams are at 14 of 20 (70 percent) and 7 days while the comparison team went from 30 to 35 percent. The gap, not the raw rise, is the signal. Adjust rules, then extend in waves.

Worked example (illustrative)
A team splits one 3-page setup guide into nine tiny pages to raise its count. Under the program the credit came from reader-rated usefulness and freshness, so nine thin pages earn less, the peer sample flags fragmentation, and the reviewer merges them, crediting the merge.

Trade-offs and pitfalls

• Extrinsic rewards can crowd out pride in the work, so keep rewards modest and tied to helping others.
• Heavy scoring becomes a job of its own. Keep to three or four signals.
• What would change my call: in a very small team, direct manager expectations beat a formal program.

Direct answer

Link docs to code through stable identifiers (a service name and the paths or symbols it owns), not through line numbers or pasted URLs. Store those identifiers as metadata in each doc, run a check in CI (continuous integration, the automated build that runs on every pull request) that fails when a link no longer resolves, and run a scheduled sweep for links that rot without a PR touching them. When a break is found, the tooling proposes the repair (for example the renamed path) so a human only approves.

1. What metadata you record

Put it in the doc's front matter (a small YAML header at the top of a Markdown file), so it travels with the doc in the same repository ("docs-as-code": docs live in version control and go through review like code).

---
service: billing
owner_team: payments
covers:
  - src/billing/
last_verified_commit: abc1234
review_by: 2026-12-01
---

• covers: paths (or symbol names for API docs, where a symbol is a named code element such as a function or class) the doc describes. This is the forward link, doc to code.
• owner_team plus a CODEOWNERS file (a repository file mapping paths to the people who must review changes there) gives the reverse link and someone to notify.
• last_verified_commit and review_by: when a human last confirmed the doc matched the code. A commit SHA (the unique hash Git gives every commit, such as abc1234) records exactly which version of the code was checked.
• The service: billing value is an identifier from a service catalog (an internal registry listing each service, its owning team and where its code lives). If the code moves from one repository to another, only the catalog entry (billing -> repo: platform-monorepo, path: services/billing/) is updated, and every doc that says service: billing still resolves. Docs that hard-code a repository URL would all break.
• Links from doc prose to code use a stable anchor (a symbol or section name). A permalink pinned to a commit SHA never breaks but shows old code, so use it only as evidence ("this was true at abc1234"), and use the live path for navigation.

2. Where checks run

• On every pull request: compute the files changed; find docs whose covers overlap; require either a doc edit or an explicit "docs not needed" label. Also run the link resolver below on the whole docs folder.
• Nightly sweep: catches external links, docs past review_by, and services whose owner team no longer exists.
• Reverse index: a generated page listing each service and its docs, so engineers finding code can find docs.

3. Detecting and repairing broken links (worked example)

A PR renames src/billing/ to src/invoicing/. The check below reads each doc's covers, confirms each prefix still matches a tracked file, and uses git diff -M (which detects renames) to suggest the new location. Setup: pip install pyyaml; a repo with src/billing/charge.py, src/billing/refund.py and the doc above (saved as docs/billing-runbook.md) committed on branch main; then create a branch, run git mv src/billing src/invoicing and commit.

import subprocess, sys, pathlib, yaml

def front_matter(path):
    text = path.read_text()
    if not text.startswith("---\n"):
        return None
    return yaml.safe_load(text.split("---\n", 2)[1])

def git(*args):
    return subprocess.run(["git", *args], capture_output=True, text=True, check=True).stdout

base = sys.argv[1]  # e.g. origin/main
tracked = git("ls-files").splitlines()
renames = {}
for line in git("diff", "--name-status", "-M", base, "HEAD").splitlines():
    parts = line.split("\t")
    if parts[0].startswith("R"):
        renames[parts[1]] = parts[2]

problems = 0
for doc in pathlib.Path("docs").rglob("*.md"):
    meta = front_matter(doc)
    if not meta:
        print(f"{doc}: MISSING front matter"); problems += 1; continue
    for prefix in meta.get("covers", []):
        if any(f.startswith(prefix) for f in tracked):
            continue
        hint = next((new for old, new in renames.items() if old.startswith(prefix)), None)
        msg = f"{doc}: covers '{prefix}' matches no file"
        if hint:
            msg += f" (renamed to {hint.rsplit('/', 1)[0]}/)"
        print(msg); problems += 1
print(f"{problems} problem(s)")
sys.exit(1 if problems else 0)

Run as python3 check_doc_links.py main (the argument is the branch to compare against). Output:

docs/billing-runbook.md: covers 'src/billing/' matches no file (renamed to src/invoicing/)
1 problem(s)

How it works, block by block: front_matter reads the YAML header of a doc. renames is a dictionary built from git diff -M (the -M flag makes Git detect that a file was moved rather than deleted and re-added), mapping old path to new path, for example src/billing/charge.py to src/invoicing/charge.py. For each doc and each covers prefix, the loop asks whether any tracked file still starts with that prefix (startswith). If none does, the link is broken, and the loop looks for a renamed file whose old path started with that prefix to suggest the repair.

The CI job exits non-zero, so the rename PR cannot merge until the doc's covers is updated. A bot can open that one-line fix automatically, because the rename target is already known.

4. Trade-offs and pitfalls

• Strict blocking on every code change creates label-spam ("docs not needed" clicked reflexively). Start warn-only for a quarter, then block only for services tagged tier-1 (the most business-critical services, for example those that can page someone at night).
• Path prefixes are coarse: a rename inside the folder is not detected. Symbol-level links are more precise but need per-language tooling, so reserve them for public API docs.
• Metadata rots too. review_by with a nightly report of expired docs is the guard.
• Docs living outside the repo (a wiki) cannot get a PR check. Either move the ones that matter into the repo, or accept only the nightly sweep for them.

Direct answer

A decision record (in software often called an ADR, architecture decision record) is a short note written when a decision is made. It should capture the context, the options considered, the choice, the reasoning and the consequences, so a person six months later can see why without asking. Not every decision needs one: write records for decisions that are hard to reverse, costly, cross-team, surprising or likely to be asked about again. Keep them next to the work (in the repository for engineering choices, linked from the ticket or roadmap for product choices) with one index page.

Structured elaboration

What to capture (one page is plenty)

• Title and date, and status (proposed, accepted, superseded by record N).
• Decision owner and who was consulted.
• Context: the problem, the constraints and the deadline pressure at the time.
• Options considered, with the reason each was rejected. This is the part that stops re-debate, because people who propose the rejected option can see it was already weighed.
• Decision in one sentence.
• Consequences: what gets easier, what gets harder, and what we accept.
• Revisit trigger: the condition that would reopen it ("if traffic exceeds X" or "at the next vendor renewal").

Which decisions deserve one
A quick test: would a new team member reasonably ask "why did we do it this way?" in six months, and would the answer be lost if the two people who decided left? Yes means write it. Typical yes: choosing a database (the reasons live in a few heads and are costly to redo), an API style such as REST versus GraphQL (every client depends on it), build vs buy (the cost, lock-in and staffing reasoning is rarely written elsewhere), a data retention policy (the legal reasoning matters when someone later wants to delete or keep data), a metric definition (dashboards and targets hang on it). Typical no: variable naming, a reversible feature flag default, an option you can change in an afternoon.

Where to keep them

• Engineering decisions: a docs/decisions/ folder in the repository, numbered, reviewed in a pull request (PR). They travel with the code and are found by anyone who opens the repo.
• Product or cross-team decisions: a decision-log space in the wiki, linked from the ticket and the roadmap item.
• One index (a table of number, title, status, date) so people can scan.

Worked example

Decision record 007: Store order data in PostgreSQL, not DynamoDB
Status:        Accepted (2026-03-04)
Owner:         Backend lead. Consulted: data team, finance.
Context:       Finance needs ad hoc joins across orders and refunds.
               Team has strong SQL experience, no DynamoDB experience.
Options:       (a) PostgreSQL. (b) DynamoDB: rejected, ad hoc joins would need extra pipelines.
Decision:      Use PostgreSQL with read replicas.
Consequences:  Easier reporting. Harder to scale writes past one primary.
Revisit if:    Sustained write load outgrows a single primary.

In plain words: PostgreSQL is a relational database queried with SQL, good at joins across tables. DynamoDB is a managed key-value database, fast for simple lookups but awkward for ad hoc joins. A read replica is an extra copy of the database that only serves read queries, which spreads reporting load. A single primary is the one main copy that accepts all writes, so if writes outgrow one machine, the design is harder to scale.

When someone asks in July "why not DynamoDB?", the answer is one link, and the debate is only reopened if the revisit trigger has actually fired.

Trade-offs and pitfalls

• Records that are too long are never written. Cap at one page and accept rough drafts.
• Do not edit an old record to change its meaning. Write a new one that supersedes it.
• Writing records after the fact from memory loses the rejected options, so write them as part of making the decision.
• A record folder nobody links to is invisible: link to it from the README (the repo's front-page file) and the PR template.

Direct answer

A strong answer tells a specific story: a real reproducibility pain (someone could not rerun a result), the concrete practices you introduced, how you made adoption easy rather than mandatory theatre, and a measure you can state honestly (for example how many past results could be rebuilt from the repo before and after). Below is the shape, followed by a sample story to adapt. The details are illustrative, so use your own real project.

Structured elaboration (STAR, with the detail interviewers look for)

STAR is the standard behavioral-interview format: Situation, Task, Action, Result.

• Situation: a model or analysis whose result could not be reproduced, or a new joiner who lost days rebuilding context. Reproducibility means another person can rerun the work from the repository and get the same result.
• Task: your role in fixing it, and the constraint (no one had time for heavy process).
• Action, what changed: the core is to pin everything a result depends on: the code (Git), the data (dated snapshots, meaning copies that are never edited after saving, or a data version control tool such as DVC), the environment (a lock file, which records the exact version of every library, or a container image, a packaged copy of the whole software setup), the randomness (fixed seeds, meaning setting the random number generator's starting value so runs repeat) and the experiment record (a tracker such as MLflow that stores parameters, metrics and code commit). Named tools like DVC and MLflow are optional examples; the practices are what matter. Document in a README (how to run) and a model card (a short document stating a model's purpose, training data, limits and owner).
• Action, adoption: a project template that already contains these files, a CI (continuous integration) job that runs the pipeline end to end on a small sample, a pull request checklist, a short demo, and pairing with the first two teammates.
• Result: a before/after measure you can defend, plus the behaviour change.

For instance, before the change: "the churn notebook could not be rerun"; after: "a teammate reran it from the README in one sitting".

Worked example

Situation. A churn model owned by a colleague who left could not be retrained. The notebook depended on a table that had changed, and no one knew the library versions used.

Task. As the ML engineer picking it up, I was asked to make it maintainable and to stop it happening to the next model.

Action. I rebuilt the model from the repo history and recorded the gaps: no data version, no environment file, seeds not set. For that one model I added a lock file, dated data snapshots, fixed seeds, an MLflow run per training and a README with a "reproduce in five commands" section, plus a model card. Then I made it cheap for others: I put all of this in a project template, so a new project starts compliant. A CI job retrains on a 1% sample and compares the metric to a stored value within a tolerance, so drift in the environment is caught. I demoed it in the team meeting and paired with two colleagues to port their projects. I did not make it mandatory at first. After it caught a broken dependency upgrade in CI, the team lead made the template the default.

Result (illustrative, adapt to yours). I audited the last five models before the change: two could be rebuilt from the repo alone. After porting, all five could, verified by a teammate running the README commands cold. Onboarding (getting a new teammate productive) onto a model dropped from "several days of asking around" to a first successful rerun on day one. I would state it in that plain form: counts I actually checked, not a percentage I cannot back up.

Trade-offs and pitfalls

• Do not claim precision you did not measure. "Five of five reproduced by a teammate from scratch" is stronger than an invented improvement figure.
• Tools alone do not fix documentation. The template and CI check are what change habits.
• Bit-for-bit reproducibility can be impossible because GPU nondeterminism (parallel hardware adding numbers in a varying order) makes reruns differ slightly. Say what tolerance you define as "reproduced", for example a metric within 0.5 points of the stored value.
• Weak answers name tools but not the resistance you met. Say who pushed back and what changed their mind.