Skip to the content ForoHackers
Log inJoin

Technical writing: start here

Technical writing
#2885 · · Quote · Report

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

  1. Rewrite a confusing paragraph from a project you use in half the words, keeping every fact.
  2. Write a how-to for a task you just learned, then watch someone follow it and note where they stall.
  3. Learn a lightweight markup such as Markdown and build a short multi-page guide.
  4. Write one tutorial and one reference page for the same feature, and compare their shapes.
  5. 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

You are not logged in, so this goes up anonymously: no account, no name and no address is stored with it, and it may carry no link and no image. Log in or join to post under your name. Our web server's logs keep the address and time of every request for up to 14 days; to keep yours out of them, use Tor. To reach the staff in confidence, use the drop. Sign as a returning source (a key kept only in this browser)

Sending takes a few seconds here: your browser first works out a proof of work against spam.

Reply