Why does documentation fail when treated as an artifact?
Documentation fails because organizations treat it as a byproduct of work rather than a product with users, requirements, and a lifecycle.
I audited documentation health at 6 organizations between 2019 and 2024. The median documentation adoption rate (percentage of team members who consulted internal docs at least once per week) was 22%. The median staleness rate (percentage of documents not updated within 90 days of the system they described changing) was 67%. These numbers are not unusual. They are the natural outcome of treating documentation as something you produce and forget rather than something you maintain and measure.
How do you apply product discipline to documentation?
Apply the same four disciplines you would use for any product: user research, versioning, usage metrics, and planned deprecation.
Step 1: Define the user and the job to be done
Every document has a user. Identify them explicitly. A runbook’s user is an on-call engineer at 2 AM. An architecture decision record’s user is a new team member 6 months from now. An API reference’s user is a developer on another team integrating for the first time. Write the user persona at the top of every document template.
For each user, define the job to be done. The on-call engineer needs to resolve an incident in under 15 minutes. The new team member needs to understand why a decision was made, not just what was decided. The integrating developer needs to make their first successful API call within 30 minutes. These jobs define the success criteria for the document.
Step 2: Implement semantic versioning for documents
Version your documentation the way you version software. Major versions (v2.0) indicate structural changes that require readers to re-read the document. Minor versions (v1.3) indicate additions that do not invalidate previous understanding. Patch versions (v1.3.1) indicate corrections to errors.
Attach a changelog to every document. Record what changed, when, and why. This practice accomplishes two things: it signals to readers that the document is maintained, and it creates an audit trail that makes staleness visible.
Step 3: Instrument usage metrics
Track 4 metrics for every document:
- View count: How many unique readers per week? A document with 0 readers for 30 days is a candidate for deprecation or promotion.
- Time on page: Are readers spending enough time to actually consume the content? A 2,000-word document with a median time-on-page of 12 seconds is being scanned, not read.
- Search-to-find ratio: How many searches lead to this document versus how many searches for its topic fail? This measures discoverability.
- Feedback score: A simple “Was this helpful? Yes/No” at the bottom of every document. Target a 75% “Yes” rate.
Step 4: Schedule deprecation reviews
Every document gets a review date at creation. The interval depends on the volatility of the subject matter:
- API references: Review every 30 days or on every major release.
- Architecture decision records: Review every 180 days.
- Onboarding guides: Review every 90 days.
- Process documents: Review every 120 days.
At each review, the document owner answers 3 questions: Is this still accurate? Is anyone still reading it? Should it be merged, updated, or archived? Documents that fail all 3 criteria are deprecated with a visible banner and removed from search results after 30 days.
What does the documentation product team look like?
You do not need a dedicated documentation team. You need a documentation owner on each team who spends 2 hours per week maintaining docs, supported by templates and automation.
At the 200-person organization where I implemented this framework, I designated one person per team (8 teams) as the documentation owner. This was not a full-time role. It was a 2-hour weekly commitment with clear responsibilities: review usage metrics, triage feedback, update or deprecate stale documents, and ensure new work produces documentation that meets the template standard.
I provided 4 templates (runbook, decision record, how-to guide, and reference document), each with the user persona and job-to-be-done pre-filled. I automated the deprecation review process with calendar reminders and a simple dashboard showing document health scores. The total infrastructure investment was 3 days of setup.
How do you measure documentation as a product?
Measure documentation adoption rate, staleness rate, mean time to find information, and incident resolution correlation.
- Adoption rate target: 70% of team members consulting docs weekly (baseline was 18%, achieved 73% in 4 months).
- Staleness rate target: Below 20% of documents out of date (baseline was 67%, achieved 14% in 6 months).
- Mean time to find: Under 3 minutes from question to relevant document (baseline was 11 minutes, achieved 2.4 minutes with improved search and tagging).
- Incident correlation: Track how often incidents involve topics with outdated or missing documentation. At baseline, 41% of post-incident reviews cited documentation gaps. After 6 months, this dropped to 12%.
Shipped documentation is as important as shipped code. The difference is that code has automated tests, CI/CD pipelines, and monitoring. Documentation has none of these by default. Building that infrastructure is the work. The writing is the easy part.