Saltar al contenido ForoHackers

Technical writing: start here

Redacción técnica
#379 · Ophuscado · · Denunciar

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

Inicia sesión o únete para responder.