Technical Writing
Write documentation that developers actually read - clear README files, API references, tutorials, and architecture decision records that reduce support burden.
skill: Technical Writing category: Developer Experience tags: [Technical Writing, Documentation, API Docs, README, Developer Experience] readingTime: 5
Good documentation is a force multiplier - bad documentation is a support ticket. The goal is not to document everything; it's to document the right things at the right abstraction level. Tutorials help beginners get started; references serve advanced users mid-task. Never mix them in the same document.
Workflow
- Write a great READMEThe README is the front door of your project - a developer decides in 30 seconds whether to use your library or move on. Most READMEs fail this test.
- Distinguish documentation typesMixing tutorials, how-to guides, references, and explanations in one document creates a document that serves no audience well.
- Write API reference documentationDevelopers consult API docs 5-50 times per day during integration. Dense, incomplete, or example-free API docs are the #1 developer experience complaint.
- Write Architecture Decision Records (ADRs)ADRs document why technical decisions were made - preventing future engineers from undoing them unknowingly and repeating the same research.
- Maintain docs as codeDocs that live in a wiki (Confluence, Notion) diverge from the code they describe. Docs in the repo get reviewed in PRs and stay close to the code they document.
Output Format
Technical docs: README with quick start, Diátaxis-structured docs, API reference with examples, and ADRs for key decisions.
docs/
├── README.md # Quick start + why/when
├── tutorials/ # Learn X by building Y
├── how-to/ # Task-specific guides
├── reference/ # API, CLI, config reference
├── explanation/ # Concepts and architecture
└── adr/
├── 0001-database.md
└── 0002-auth.mdExamples
Input
Output
Edge Cases & Gotchas
- Docs for features that don't exist yet - Documenting planned features as if they're shipped misleads developers and damages trust. Mark future features clearly: '[Coming Q4 2026]' or use a separate roadmap doc.
- Code examples that don't work - Nothing erodes developer trust faster than copy-pasted code that throws an error. Test every code example in docs with a CI job that runs them.
- Version-specific docs - Docs that don't specify which version they apply to cause confusion when APIs change. Always include: 'This doc applies to v2.x and later'.
- Missing 'what not to do' - Showing only the happy path leaves developers to discover edge cases by crashing in production. Include error cases, what to avoid, and debugging tips.
When to Break These Rules
- Use a dedicated docs platform (Mintlify, Readme.com, Gitbook) instead of Docusaurus when the team doesn't want to maintain a docs site - these tools handle hosting, search, and API spec import.
- Write shorter docs for internal tools - exhaustive documentation for a script used by 3 people wastes more time than the documentation saves.
Reference Files
https://diataxis.fr/https://www.writethedocs.org/guide/