JobCannon
全部技能

Documentation Writing

⬢ 層級 3軟技能
中等
薪資影響
4 個月
學習時長
中等
難度
4
職業
一覽

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).

什麼是 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)

🔧 工具與生態
NotionConfluenceGitBookDocusaurusMintlifyMkDocsHugoMermaidExcalidrawdraw.ioAsciidoctorRead the DocsBackstage TechDocs

📋 開始之前

Communication

💰 各地區薪資

地區初級中級高級
USA$90,000$135,000$185,000
UK£50,000£80,000£115,000
EU€55,000€85,000€120,000
CANADACA$95,000CA$140,000CA$190,000

❓ 常見問題

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.

不確定這項技能適不適合你？

做一下職業匹配，我們會推薦合適的方向。

找到最適合我的技能 →

找到理想的職業方向

在 2,521 個職業中進行技能匹配。免費。

免費做職業匹配 →