Skip to the content ForoHackers
Log inJoin

Redacción técnica: por dónde empezar

Technical writing
#380 · Ophuscado · · Report

La redacción técnica es explicar cosas complejas para que el lector pueda actuar: instalar una herramienta, llamar a una API, entender un diseño. La buena prosa técnica es sencilla, exacta y se organiza en torno a lo que el lector quiere hacer. Es una habilidad propia, y los ingenieros que la tienen destacan.

Conceptos clave

  • Audiencia: decidir quién lee, qué sabe ya y qué necesita hacer a continuación.
  • Estructura: un título claro, un resumen breve al principio, encabezados y una idea por párrafo.
  • Lenguaje claro: frases cortas, palabras concretas, voz activa, términos definidos una vez y usados siempre igual.
  • Ejemplos: una muestra que funciona enseña más rápido que un párrafo que la describe.
  • Revisión: redactar, recortar, probar las instrucciones con otra persona y volver a editar.

Vocabulario

  • Guía de estilo: las reglas de redacción, formato y terminología que acuerda un equipo.
  • Lenguaje claro: escritura pensada para entenderse a la primera lectura.
  • Tutorial y referencia: uno enseña guiando, la otra enumera datos para consultar.
  • Corrección de estilo: una pasada de gramática, coherencia y claridad, no de contenido.

Qué estudiar, en orden

  1. Reescribe con la mitad de palabras un párrafo confuso de un proyecto que uses, sin perder ningún dato.
  2. Escribe una guía práctica de una tarea que acabas de aprender, y observa a alguien seguirla para ver dónde se atasca.
  3. Aprende un marcado ligero como Markdown y arma una guía corta de varias páginas.
  4. Escribe un tutorial y una página de referencia de la misma función, y compara sus formas.
  5. Lee una guía de estilo, adopta sus reglas y aplícalas a un documento tuyo.

Etiquetas relacionadas

#documentation #developer-relations #api-design #open-source-community

Log in or join to reply.