Saltar al contenido ForoHackers

Technical writing: start here

Redacción técnica
#2885 · · Citar · 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

No has iniciado sesión, así que esto se publica como anónimo: no se guarda con ello ninguna cuenta, nombre ni dirección, y no puede llevar enlaces ni imágenes. Inicia sesión o únete para publicar con tu nombre. Los registros de nuestro servidor web guardan la dirección y la hora de cada petición hasta 14 días; para que la tuya no quede en ellos, usa Tor. Para escribir al equipo de forma confidencial, usa el buzón. Firmar como fuente habitual (una clave guardada solo en este navegador)

Enviar tarda unos segundos aquí: tu navegador resuelve antes una prueba de trabajo contra el spam.

Responder