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
- Reescribe con la mitad de palabras un párrafo confuso de un proyecto que uses, sin perder ningún dato.
- Escribe una guía práctica de una tarea que acabas de aprender, y observa a alguien seguirla para ver dónde se atasca.
- Aprende un marcado ligero como Markdown y arma una guía corta de varias páginas.
- Escribe un tutorial y una página de referencia de la misma función, y compara sus formas.
- 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