Product VP here, but I learned from engineering: bad tooling kills documentation culture.
Thesis
If writing docs feels like extra work, engineers won’t do it. Tooling must feel like coding.
Example: Confluence to Docusaurus
We moved from Confluence to Docusaurus (docs-as-code). Contribution rate increased 3x.
Why? Engineers already use Git, Markdown, code review. Docs fit existing workflow.
Tool Landscape
Docusaurus: Open source, React-based, great for public docs
Mintlify: Beautiful UX, AI-powered search, good for API docs
Backstage: Internal developer portal, integrates with service catalog
Notion: Easy to use, but not version-controlled—risky for engineering docs
Tooling Requirements
- Version control (Git-based)
- Code review integration (PRs for doc changes)
- Easy local preview
- Fast, accurate search
- Templates (reduce decision fatigue)
Measurement Challenge
How do you know if docs are working?
Metrics to track:
- Time-to-first-PR for new hires
- Support ticket volume (decreases when docs improve)
- Doc search analytics (what are people looking for?)
- Staleness (last updated date)
- Contribution rate (% of engineers who update docs)
Business case: Documentation problems cost 15-25% of engineering capacity. Measuring impact justifies investment.
Open Questions
- Self-host or use SaaS for docs?
- How do you handle customer-facing vs internal docs (same tool or separate)?
- What metrics convince leadership to invest in docs tooling?
What’s your docs stack? What metrics do you track?
Our stack: Backstage (internal portal), Docusaurus (public docs), Confluence (deprecated legacy content).
Backstage Choice
Integrated with service catalog—each service has docs, runbooks, on-call info in one place.
Migration Story
Moved from Confluence to docs-as-code over 6 months. Engineers resisted at first, but Git-based docs enabled code review culture.
Tooling Investment
Dedicated platform engineer owns docs infrastructure—not an afterthought.
Metrics Tracked
- Doc coverage: % of services with complete docs (target: 100%)
- Freshness: Average age of last update (target: <90 days)
- Search usage: Top searches reveal doc gaps
- Contribution: # of engineers who updated docs per quarter
ROI story: Calculated docs improved onboarding saves ~K annually (reduced time-to-productivity).
AI Integration
Experimenting with AI-powered docs search (natural language queries).
Question: Do you use AI to auto-generate docs from code, or too risky for accuracy?
Financial services requirements: Docs must be auditable, version-controlled, access-controlled.
Stack
GitLab (version control), Docusaurus (rendering), internal approval workflow.
Compliance Benefit
Git history provides audit trail—who changed what, when, why.
Security
Sensitive docs in private repos. Public docs in public repos.
Template Enforcement
Pre-commit hooks check that ADRs follow required template.
Metrics for Compliance
- % of architecture changes with ADRs (target: 100%)
- Runbook coverage for critical services (target: 100%)
- Doc review cycle time
Integration
Docs linked to Jira tickets—traceability from requirements to docs to code.
Question: How do you handle sensitive/confidential information in docs? Separate repo or redaction?
Design perspective: documentation tools need great UX or engineers won’t use them.
Tool Evaluation
Tested Docusaurus, GitBook, Mintlify, Notion. Chose Mintlify—beautiful out-of-the-box, easy navigation, AI search, low setup.
UX Principles for Docs
- Fast search (users search, don’t browse)
- Clear hierarchy (findability > comprehensiveness)
- Mobile-friendly (engineers read docs on phones during incidents)
- Syntax highlighting (code examples must be readable)
Design System Analogy
Docs are product—treat them with same design rigor.
Accessibility
Docs must meet WCAG standards—screen reader compatible, keyboard navigable.
Metrics from Design Perspective
- Task completion: Can user find answer in <2 minutes?
- Search success rate: Do results answer question?
- Bounce rate: Do users leave immediately?
Question: Do you user-test documentation like you’d user-test a product feature?
EdTech startup: Started with Notion (fast, easy), migrated to Docusaurus (scalable, version-controlled).
Migration Driver
At 80 engineers, Notion became maze—docs spread across 100+ pages, no structure.
Docusaurus Benefits
Enforced structure (sidebar nav), version control (Git), code review (PRs).
Change Management
Migration was cultural challenge—engineers loved Notion’s ease.
Strategy: Migrate iteratively—onboarding docs, then runbooks, then ADRs.
Tooling Investment
Worth it—docs contribution rate increased 4x after migration.
Measurement Framework
- DX survey: How confident are you that docs are current? (scale 1-10)
- Onboarding metric: Time-to-first-PR
- Operational metric: % of incidents resolved via runbook
- Contribution metric: % of engineers who updated docs last quarter
ROI Justification
Presented to exec team—docs investment pays for itself in reduced onboarding time.
Question: How do you balance investment in docs tooling vs investment in features? Always a trade-off.