The problem: scattered, unsearchable truth
Incomplete documentation is among the costliest non-code debts. Requirements live in Slack, decisions in meetings, architecture in a senior's head, runbooks missing entirely. New hires ask the same questions; veterans duplicate answers.
PMs defer docs to "next phase"—until an incident or departure forces a rescue mission instead of a habit.
Documentation debt compounds like technical debt: each undocumented decision makes the next change slower and riskier. Investing one hour at merge time often saves many hours when the original author is unavailable.
Symptoms and costs
| Symptom | Cost |
|---|---|
| "Ask X" | Bus factor |
| Stale spec vs reality | Rework |
| Meeting decisions unrecorded | Re-debate |
| Static onboarding PDF | Stale from day one |
| Search returns nothing | Time waste |
Direct costs: rework and onboarding delay. Indirect: wrong decisions from lost context.
Framework: Capture → Structure → Publish
1. Capture — at delivery time
Light rules:
- Feature merge → wiki section or short ADR
- Meeting decision → bullet with owner and date
- Task links to wiki—not orphan docs
Post-ship capture risks fiction.
2. Structure — knowledge hub, not folder dump
A knowledge hub means:
- Taxonomy per project or domain
- Links from tasks and epics
- Search that answers questions
Folders with no board links become cemeteries.
3. Publish — meeting → wiki
Publish meeting to wiki pattern:
- Agenda + decisions + actions on one page
- Action items become tasks with back-links
- Attendees know where truth lives
Meetings without publish create entropy.
Doc levels PMs should enforce
Level 0 — Decision log — why we chose X, date, owner.
Level 1 — Runbook — deploy, rollback, on-call.
Level 2 — Light spec — scope, out-of-scope, acceptance.
Level 3 — Deep architecture — when complexity justifies it.
Not every page needs level three; every project needs level zero.
Where WKFGo helps
WKFGo offers wiki per task/project, a knowledge hub, and workflows to publish meeting notes to wiki (including MCP/API patterns). It does not auto-write docs from thin air—team discipline required.
Smart search across tasks and knowledge speeds context retrieval.
Measure doc debt in retro
Each retro ask: "What incident or delay came from missing documentation?" Repeated answers justify doc sprint allocation—perhaps ten percent capacity.
Minimal feature template
- What / Why (goal link)
- How to test
- Rollback / owner
- Related ADR link
Copy the template in wiki—authors fill fields, not blank-page terror.
Knowledge hub vs wiki per task
Wiki per task — execution context for that story.
Knowledge hub — cross-project index: standards, onboarding, architecture.
Both matter: task wikis without a hub scatter pages; a hub without task links becomes a library nobody opens.
Merge checklist
Before merging user-facing features: a wiki link exists, the decision date is on the page, the doc reviewer isn't the same person as the author, and search actually finds the page by the feature's name. PMs spot-check one random merge per sprint — culture follows inspection, not a policy slide nobody rereads.
Onboarding doc sprint
One sprint per quarter as "doc debt"—not features. Goal: top five recurring chat questions become linked wiki pages. Visible to sponsors—aligns knowledge investment.
Anti-patterns
- Documentation only for audit
- Wiki duplicates of Confluence with no owner
- "We recorded video" with no index
- Banning docs until "after release"
Getting started this week
Pick a recent task that caused rework — did it have a wiki link? If not, that's your retro action: adopt the minimal template above and the merge rule for the next sprint. Tell sponsors documentation is part of the definition of done, not optional polish squeezed in if time allows.
Frequently Asked Questions
How much documentation is enough?
If a newcomer cannot find "why" within three days, it is insufficient. Test with one retro question.
Who owns docs?
Task author—PM enforces link rules in sprint planning.
Meeting notes vs wiki?
Notes are raw; wiki is curated. Publish is step two—not optional skip.
Stale pages?
Date plus owner; flag stale in retro—refresh or archive.
Summary
Documentation is part of done: capture at delivery, structure it in the knowledge hub, and publish from meetings instead of letting decisions dissolve into memory. Without that discipline, even a good wiki tool becomes scattered storage. Start with one recent incident that had missing docs, write a single "what we learned" page linked to the task, and make the next sprint's rule simple: no merge without a wiki link for user-facing features.