Question 1

What is the Diátaxis framework and why does it matter for docs?

Accepted Answer

Diátaxis divides documentation into 4 types: Tutorials (learn-by-doing), How-to Guides (solve specific tasks), Reference (lookup facts), Explanation (understand concepts). Most orgs mix these and confuse readers ('is this a tutorial or reference?'). Applying Diátaxis = 50% reduction in help requests. Google, Stripe, Django use it. Start by categorizing existing docs, then restructure.

Question 2

READMEs vs Runbooks vs ADRs, what goes where?

Accepted Answer

README: What this repo does, how to run it, install deps. Runbook: Step-by-step ops procedures (how to deploy, handle incidents, backups). ADR (Architecture Decision Record): Why we chose X over Y, trade-offs, date, author. RFC (Request for Comments): Proposal before implementation. Reference docs: API signatures, CLI flags. How-to: Achieve a specific goal. Categorize by intent, not random.

Question 3

How do I prevent docs from getting stale?

Accepted Answer

Root cause: no owner. Fix: assign DRI per doc, auto-flag outdated docs (git commit date >6mo + no recent edits), store docs near code (same repo), auto-generate from code (docstrings, OpenAPI), include 'Last updated' in frontmatter, run doc-link-checker in CI/CD. Stripe's docs stay fresh because they own them as a product, not a side task.

Question 4

AI-generated docs in 2026, what should I do?

Accepted Answer

LLMs excel at structural scaffolding (boilerplate READMEs, runbook templates, first drafts of API docs from code). Use them for: generating doc-as-code skeletons, writing first-pass explanations, examples. Don't use for: domain-specific decisions (ADRs, trade-off analysis), technical accuracy without review. Always review + edit. Tools like Mintlify auto-generate docs from docstrings; use them.

Question 5

Style guides and consistency, how much do they matter?

Accepted Answer

Consistency > perfection. A style guide prevents: 'READMEs' vs 'Readme' vs 'readme', mixed tenses (past vs present), unexplained acronyms. Create one page (Google's is 84 pages, too much). Enforce via pre-commit hook (lint markdown, check heading hierarchy) and doc-review in PR. Automate what you can (linting, spell-check), automate what you can't by making a checklist.

Question 6

How do I build a doc culture where engineers write?

Accepted Answer

Acceptance: great docs take time, so make it frictionless. Provide templates, linters, auto-generated skeletons. Include docs in definition-of-done, review docs in PR like code. Ship a style guide, 2-page max. Celebrate docs ('this README cut our onboarding from 2 weeks to 3 days'). Tie docs to IC leveling (staff engineers known for docs). Make writing docs a career move, not admin busywork.

Regione	Livello base	Mid	Livello esperto
USA	$90k	$135k	$185k
UK	£50k	£80k	£115k
EU	€55k	€85k	€120k
CANADA	C$95k	C$140k	C$190k

Documentation Writing

Cos'è Documentation Writing

📋 Prima di iniziare

💰 Stipendio per regione

🎓 Certificazioni

🎯 Carriere che usano Documentation Writing

⚖ Confronta con

❓ Domande frequenti

Non sei sicuro che questa competenza faccia per te?

Trova il tuo percorso di carriera ideale