Technical writing is explaining complex things so a reader can act on them: install a tool, call an API, understand a design. Good technical prose is plain, exact and organised around what the reader wants to do. It is a skill of its own, and engineers who have it are noticed.
Key concepts
- Audience: decide who reads, what they already know and what they need to do next.
- Structure: a clear title, a short summary up front, headings, and one idea per paragraph.
- Plain language: short sentences, concrete words, active voice, terms defined once and used consistently.
- Examples: a working sample teaches faster than a paragraph describing it.
- Revision: draft, cut, test the instructions on someone else, then edit again.
Vocabulary
- Style guide: the rules for wording, formatting and terminology a team agrees on.
- Plain language: writing meant to be understood on the first read.
- Tutorial and reference: one teaches by guiding, the other lists facts for lookup.
- Copyedit: a pass for grammar, consistency and clarity, not for content.
What to study, in order
- Rewrite a confusing paragraph from a project you use in half the words, keeping every fact.
- Write a how-to for a task you just learned, then watch someone follow it and note where they stall.
- Learn a lightweight markup such as Markdown and build a short multi-page guide.
- Write one tutorial and one reference page for the same feature, and compare their shapes.
- Read a style guide, adopt its rules and apply them to a document of your own.
Related tags
#documentation #developer-relations #api-design #open-source-community