Technical Documentation Strategy: Diataxis, Docs-as-Code, Runbooks, Onboarding

Q: Technical Documentation Strategy: Diataxis, Docs-as-Code, Runbooks, Onboarding

Good engineering documentation is **a system, not a set of pages** — organized by purpose (Diataxis framework: tutorials, how-tos, reference, explanation), kept in version control near the code (docs-as-code), reviewed in PRs, and tested for accuracy. The main types every Java backend team needs: **README** (what is this, how to run, how to contribute), **API docs** (auto-generated from OpenAPI/Swagger or javadoc), **ADRs** (decision records), **runbooks** (operational playbooks for common incidents), **architecture diagrams** (C4 model with Mermaid/Structurizr), **onboarding guides** (week-1, week-2 paths), and **post-mortems** (incident learning). Use **Diataxis** to organize by user goal: tutorials (learning), how-tos (task), reference (information), explanation (understanding). Keep docs **close to code**: in repo `docs/`, generated from OpenAPI specs, embedded in code via Javadoc, displayed via tools like **Backstage TechDocs**, **MkDocs**, **Docusaurus**. **Test docs**: link checkers, code samples that compile and run, snapshot tests for generated content. Common mistakes: wikis that nobody updates, docs that contradict the code, no ownership, write-once-and-forget, treating docs as second-class. Senior move: build a **docs culture** — docs reviewed in PRs, every new feature requires doc updates, runbook tested in game days, onboarding measured by time-to-first-PR.

Intermediate·9 min read·

SpotifyStripeGithubSpring

Fast recall

Quick revision

Core answer

Good engineering documentation is a system, not a set of pages — organized by purpose (Diataxis framework: tutorials, how-tos, reference, explanation), kept in version control near the code (docs-as-code), reviewed in PRs, and tested for accuracy. The main types every Java backend team needs: README (what is this, how to run, how to contribute), API docs (auto-generated from OpenAPI/Swagger or javadoc), ADRs (decision records), runbooks (operational playbooks for common incidents), architecture diagrams (C4 model with Mermaid/Structurizr), onboarding guides (week-1, week-2 paths), and post-mortems (incident learning). Use Diataxis to organize by user goal: tutorials (learning), how-tos (task), reference (information), explanation (understanding). Keep docs close to code: in repo docs/, generated from OpenAPI specs, embedded in code via Javadoc, displayed via tools like Backstage TechDocs, MkDocs, Docusaurus. Test docs: link checkers, code samples that compile and run, snapshot tests for generated content. Common mistakes: wikis that nobody updates, docs that contradict the code, no ownership, write-once-and-forget, treating docs as second-class. Senior move: build a docs culture — docs reviewed in PRs, every new feature requires doc updates, runbook tested in game days, onboarding measured by time-to-first-PR.

Interview Answer9 min

Good engineering documentation is a system, not a set of pages.

The principles

Organized by purpose (Diataxis framework: tutorials, how-tos, reference, explanation)
Kept in version control near the code (docs-as-code)
Reviewed in PRs
Tested for accuracy

Main types every Java backend team needs

README (what is this, how to run, how to contribute)
API docs (auto-generated from OpenAPI/Swagger or javadoc)
ADRs (decision records)
Runbooks (operational playbooks for common incidents)
Architecture diagrams (C4 model with Mermaid/Structurizr)
Onboarding guides (week-1, week-2 paths)
Post-mortems (incident learning)

Use Diataxis to organize by user goal

Tutorials (learning)
How-tos (task)
Reference (information)
Explanation (understanding)

Keep docs close to code

In repo docs/
Generated from OpenAPI specs
Embedded in code via Javadoc
Displayed via Backstage TechDocs, MkDocs, Docusaurus

Test docs

Link checkers
Code samples that compile and run
Snapshot tests for generated content

Common mistakes

Wikis that nobody updates
Docs that contradict the code
No ownership
Write-once-and-forget
Treating docs as second-class

Senior move

Build a docs culture
Docs reviewed in PRs
Every new feature requires doc updates
Runbook tested in game days
Onboarding measured by time-to-first-PR

Why most docs are bad

Outdated, disorganized, poorly written, in the wrong place, contradictory
Solution isn't 'try harder' — engineer the documentation system

Diataxis framework (Daniele Procida)

Tutorial: learning by doing — 'Build your first Spring Boot service in 30 min'
How-to: solving a specific task — 'How to add a new database migration'
Reference: looking up information — API spec, config options, class methods
Explanation: understanding — 'How our auth works conceptually'

Mixing types is #1 cause of bad docs: tutorial that suddenly explains theory, reference that includes opinions, how-to with too much background. Separating clarifies purpose.

Doc types detail

1
README at every repo root: what, why, how to run, test, where to ask
2
API documentation: OpenAPI/Swagger for REST; AsyncAPI for events; gRPC reflection
3
Architecture diagrams: C4 (Context, Container, Component) with Mermaid/Structurizr
4
ADRs: decision history
5
Runbooks: operational playbooks for incidents and routine ops
6
Onboarding guides: week-1, week-2, month-1 paths
7
Post-mortems: incident learnings, blameless
8
Service catalog entry (Backstage/Cortex): owners, dependencies, on-call rotation
9
Conceptual/explanation docs: how the system works above code
10
Troubleshooting guides: common errors and fixes
11
Style guide / engineering principles

Docs-as-code principles

Docs in version control (Git)
Same workflow as code: branch, edit, PR, review, merge
Same tooling: linting, testing, deployment
Generated docs (OpenAPI, Javadoc) regenerated on build
Reviewed by humans + automated checks

Why this works

Versioned with code; never stale relative to release
PR reviewer ensures docs reflect changes
Merge conflicts surface conflicting changes
CI tests docs (link rot, code samples, spelling)
Distribution via static site is fast + cheap + searchable

Tooling stack

Static site generators

MkDocs with Material theme: Markdown, simple, fast
Docusaurus (Meta): React-based, versioning, i18n
Sphinx (Python ecosystem); Hugo; Jekyll
Backstage TechDocs (Spotify): MkDocs integrated with service catalog

API docs

springdoc-openapi: auto-generates OpenAPI from Spring annotations
Swagger UI / Redoc: human-readable browser
Stoplight: API design + docs platform
AsyncAPI: event-driven contracts

Diagrams as code

Mermaid: text → diagrams in Markdown; widely supported
PlantUML: more types; older
Structurizr: C4 native
Excalidraw: hand-drawn whimsical
draw.io: GUI, save XML in Git

Service catalog

Backstage (Spotify): catalog + docs + plugins
Cortex: maturity scorecards + docs
OpsLevel: similar

Organization (Diataxis-aligned)

docs/index.md landing
docs/tutorials/01-build-first-service.md, 02-add-database.md (learning)
docs/how-to/add-new-endpoint.md, add-database-migration.md, debug-failing-test.md (task-oriented)
docs/reference/api/ auto-generated OpenAPI, config/, metrics-emitted.md (information)
docs/explanation/architecture-overview.md, auth-model.md, event-flow.md (conceptual)
docs/adr/0001-use-postgres.md, 0007-event-sourcing.md (decisions)
docs/runbooks/incident-high-error-rate.md, rotate-secrets.md (ops)

Per-repo README minimum

order-service: processes customer orders
Quick start: docker compose up; ./mvnw spring-boot:run; curl localhost:8080/health
Testing: ./mvnw test (unit); ./mvnw verify (integration)
Documentation: links to architecture, API reference, runbooks, ADRs
On-call: Slack #order-service-alerts; PagerDuty order-team; Owner orders@

API doc example (Spring Boot)

@Operation(summary='Create a new order', responses=[@ApiResponse 201 Created, @ApiResponse 400 Invalid input])
@PostMapping('/orders') createOrder(@Valid @RequestBody CreateOrderRequest req)
springdoc-openapi reads annotations; generates /v3/api-docs; Swagger UI at /swagger-ui.html

Runbook template

Symptoms: p99 latency >2s; error rate >5%; alerts OrderServiceErrorRate firing
Triage steps: check Datadog dashboard; check recent deploys (kubectl rollout history); check downstream payment/inventory; check DB connection pool, slow queries
Rollback: kubectl rollout undo deployment/order-service
Common causes: recent deploy → rollback; DB connection exhaustion → check pool size, restart; downstream payment down → enable degraded mode (flag payments.fallback)
Escalation: 15 min page tech lead; 30 min page director
Runbooks tested in game days; proven to work

Maintenance

Doc updates required in feature PRs: reviewer checks; CI may enforce
Stale doc detection: dates/'last reviewed'; quarterly stale-doc cleanup
Owner per doc: every doc has team owner; rotation when team changes
CI checks: link rot, spelling, code-sample compilation, doc lint
Analytics: which docs viewed; which never; remove or improve
Annual doc audit: pick top docs; verify accuracy; update or archive

CI doc checks

jobs.docs.steps: lycheeverse/lychee-action link checker; markdownlint docs/; mkdocs build --strict (fails on warnings); ./scripts/test-code-samples.sh; rojopolis/spellcheck-github-actions

Common pitfalls

1
Wiki dumps: 5000 unorganized pages; nobody finds
2
Docs contradict code: trust eroded; engineers ignore
3
No ownership: nobody updates; rot accumulates
4
Mixed Diataxis types: confusing
5
No discoverability: great doc nobody knows exists
6
Wall-of-text: no structure, headings, diagrams
7
Missing why: only what; future engineers wonder
8
No code samples: abstract; engineers want copy-paste
9
Outdated screenshots: UI changed, screenshots didn't
10
Docs in 5 places: Confluence + Notion + Wiki + Google Docs + repo; fragmented
11
No on-ramp: seniors know everything; new hires drown
12
Runbooks never tested: real incident; runbook wrong

Culture moves

'Docs are part of feature': not done until docs done
'README-driven development': write README first, then build
Doc reviews valued: peer review docs like code
Doc days: quarterly; team writes/improves
Documentarian role/champion: not separate team; embedded engineer who cares
Onboarding measures docs quality: new hires document what they wished they had
Praise and reward good docs publicly

Onboarding-specific

Week 1: read X, run dev env, ship small PR
Week 2: shadow on-call, attend planning, deeper area dive
Month 1: own feature end-to-end
Measure: time to first PR; time to first deploy; time to on-call ready
Update onboarding based on new-hire feedback (fresh eyes)

Trade-offs

Centralized vs per-repo

Central: one search, consistent nav; can outdate
Per-repo: close to code, owned; harder to find across
Hybrid: distributed authoring; centralized aggregation (Backstage TechDocs)

Generated vs handwritten

Generated (OpenAPI, Javadoc): always accurate; can be verbose/impersonal
Handwritten: warmth, examples, opinions; can drift
Both: reference generated; tutorials/explanation handwritten

Wikis vs docs-as-code

Wikis (Confluence, Notion): easy edit; poor versioning; no PR review
Docs-as-code (Markdown Git): heavier edit; PR-reviewed; versioned with code
Modern: docs-as-code for eng docs; wikis for cross-functional/business

Strict templates vs free-form

Strict: consistent; rigid
Free-form: flexibility; chaos
Right: templates for ADR/runbook/post-mortem; free for tutorials

Small team vs large org

Small: README + ADR + runbooks may suffice
Large: service catalog, central docs site, dedicated tooling
Scale incrementally; don't pre-build for 100 services

Honest critique

Docs are work; nobody loves writing them
Best docs from engineers who pair on docs as much as code
AI-generated tempting but lack judgment; review still needed
ROI delayed: pain saved in incident, onboarding, refactoring
Some teams over-index on process and ship less; balance matters

Maturity ladder

1
Docs in Slack/nowhere
2
Some READMEs; wiki dumps
3
Per-repo docs/; ADRs adopted
4
Diataxis organization; docs-as-code; CI checks
5
Service catalog (Backstage); central + distributed; runbook testing
6
Docs reviewed in PRs standard; onboarding measured; analytics-driven

Senior engineer moves

Build the docs system: choose tools, set conventions, evangelize
Lead by example: write good READMEs, ADRs, runbooks; teams follow
Pair on docs review: critique tone, structure, accuracy
Test runbooks in game days: discover gaps before real incidents
Maintain the index/catalog: discoverability
Track doc ROI: time saved in onboarding, incidents, code review
Refactor docs: same energy as code refactoring
Standardize templates: ADR, runbook, README, post-mortem
Use Diataxis explicitly: organize folders accordingly
Pair docs + code: every PR with API change updates OpenAPI; every architecture change updates ADR + diagram
Own a few docs personally: accountable for their quality

Strategic take

Documentation is engineering work; treat as such
Diataxis organizes by purpose; docs-as-code keeps fresh; CI catches rot
Runbooks tested in game days; not theory
README + API docs + ADRs + runbooks + onboarding are core five
Seniors build culture, lead by example, build tooling, measure outcomes
Goal: docs engineers actually read, trust, contribute to

Interview-ready guide

Interview answer