Documentation-as-Code Requires Tooling That Doesn't Suck—Docusaurus, Mintlify, Backstage. What's Your Stack and How Do You Measure Success?

General
1

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

  1. Self-host or use SaaS for docs?
  2. How do you handle customer-facing vs internal docs (same tool or separate)?
  3. What metrics convince leadership to invest in docs tooling?

What’s your docs stack? What metrics do you track?

2

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?

3

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?

4

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?

5

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.