Documentation & Writing · Soft Skills & Ecosystem Deep Dive

The Four Doc Types

Diátaxis

Type	Audience need	Example
Tutorial	Learning by doing	"Build your first chart in 10 minutes"
How-to guide	Solve a specific problem	"How to deploy to staging"
Reference	Look up a fact	API docs, config schema
Explanation	Understand the why	"How our cache invalidation works"

Mixing types is the #1 doc smell — a tutorial that becomes a reference midway loses both audiences.

The Working Set

README — what the project is, how to run it locally, how to contribute, where the docs live. Top of repo, kept current.
ADRs (Architecture Decision Records) — short notes on why a design choice was made. Status, context, decision, consequences. /docs/adr/0001-use-postgres.md.
Runbooks — step-by-step ops procedures. "What to do when alert X fires." Linked from every alert.
Postmortems — blameless incident write-ups. What happened, why, what we're changing.
API docs — OpenAPI/Swagger for REST, schema introspection for GraphQL, generated where possible.
CHANGELOG — human-readable per-release notes. Keep a Changelog format is the standard.
CONTRIBUTING / CODE_OF_CONDUCT — for any repo accepting outside PRs.

Habits

Docs in the repo, not the wiki. Markdown next to code travels with branches and survives org changes.
Update in the same PR as the code change. Otherwise it never happens.
Review docs. Doc PRs get reviewed like code; same standards.
Write the README first for new projects (README-driven development) — surfaces the user experience early.
Diagrams as code — Mermaid, PlantUML, ExcaliDraw — version-controlled, not screenshots.
Owner per doc. Unowned docs rot.
Doc days / freshness audits. Quarterly sweep to delete obsolete pages.

Postmortems

Blameless — focus on the system, not the human. Assume good intent.
Timeline — what happened in chronological order, with timestamps.
Impact — quantified: users affected, revenue lost, SLO burn.
Root cause(s) — Five Whys; surface symptom is rarely the cause.
Action items — owner + date for each. Track to completion.
What went well — celebrate the good response too. People learn from both.
Share widely. Post in #incidents or company-wide; learning travels only if it's read.

Tradeoffs

Docs that lie. Worse than no docs. Stale instructions waste hours and erode trust.
Wall of text. Lead with the headline; nest detail.
Auto-generated everything. Generated reference is fine; generated explanation is gibberish.
Lost in the wiki. If search doesn't find it in 10 seconds, it doesn't exist.
Doc-as-process. A 40-page onboarding doc nobody reads ≠ onboarding.
Comments as docs. Inline comments age fast; high-level explanation belongs in repo docs, not in code.

Continue