JobCannon
All skills

Documentation Writing

⬢ TIER 3Soft
Medium
Salary impact
4 months
Time to learn
Medium
Difficulty
4
Careers
TL;DR

Documentation Writing is the discipline of creating clear, discoverable internal docs (READMEs, ADRs, runbooks, design docs, RFCs) that scale team knowledge and reduce onboarding time. Distinct from technical-writing (external copywriting). Career path: Junior (README+comments, $80-110k) → Mid (ADRs+design docs, $110-150k) → Senior (doc systems+style guides, $150-200k+). Built on clarity (Diátaxis framework: tutorials/howtos/reference/explanation), tools (Notion, Confluence, GitBook, Docusaurus, Backstage TechDocs), and doc-as-code practices (Git, CI/CD, auto-generated from code).

What is Documentation Writing

Write clear docs: API docs, architecture diagrams, runbooks, READMEs. Make knowledge accessible, reduce "tribal knowledge." Underrated career multiplier. Learning Curve: Medium (clarity + empathy for readers)

🔧 TOOLS & ECOSYSTEM
NotionConfluenceGitBookDocusaurusMintlifyMkDocsHugoMermaidExcalidrawdraw.ioAsciidoctorRead the DocsBackstage TechDocs

📋 Before you start

Communication

💰 Salary by region

RegionJuniorMidSenior
USA$90k$135k$185k
UK£50k£80k£115k
EU€55k€85k€120k
CANADAC$95kC$140kC$190k

❓ FAQ

What is the Diátaxis framework and why does it matter for docs?
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.
READMEs vs Runbooks vs ADRs — what goes where?
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.
How do I prevent docs from getting stale?
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.
AI-generated docs in 2026 — what should I do?
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.
Style guides and consistency — how much do they matter?
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.
How do I build a doc culture where engineers write?
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.

Not sure this skill is for you?

Take a 10-min Career Match — we'll suggest the right tracks.

Find my best-fit skills →

Find your ideal career path

Skill-based matching across 2,536 careers. Free, ~10 minutes.

Take Career Match — free →