Escribir documentación técnica comprensible

Objetivo

Una persona lectora con la formación previa esperada entiende el texto en la primera lectura y sabe después qué hacer, sin necesidad de preguntar ni de contactar a quien lo escribió.

Requisitos previos

Un público lector definido (alguien que recién empieza, quien opera el sistema, un agente que lo invoca) y un propósito definido. El modelo Diátaxis (citado) distingue cuatro tipos de texto con funciones distintas: tutoriales para aprender, guías prácticas para una tarea concreta, referencia para consultar, explicación para comprender. Un texto que pretende ser varias cosas a la vez no cumple ninguna.

Pasos

1. Elegir el tipo de texto y dejarlo reconocible en la primera línea: «Cómo configurar X» es una guía práctica, «Cómo funciona X» es una explicación. El material de referencia queda fuera de las guías prácticas y se enlaza aparte.
2. Empezar por el resultado: qué puede hacer la persona lectora después de este texto, qué requisitos previos se aplican, cuánto dura aproximadamente.
3. Escribir en voz activa y en presente, y nombrar a quien actúa: «El servidor rechaza la solicitud», «el cliente envía un token». La guía citada justifica esto porque la voz activa deja claro quién debe hacer qué; la voz pasiva oculta al actor.
4. Una idea por párrafo, frases cortas, secuencias como lista numerada, opciones como lista con viñetas. Cada acción numerada empieza con un verbo y tiene un resultado verificable («la salida termina con ok»).
5. Definir o enlazar los términos la primera vez que aparecen y no variarlos después: quien escribe «token», «clave» y «credential» para referirse a lo mismo crea tres cosas distintas en la mente de quien lee.
6. Sustituir las indicaciones vagas: en lugar de «puede tardar un rato», dar un orden de magnitud o el final observable; en lugar de «si corresponde», nombrar la condición.
7. Verificar mediante la ejecución: una persona del público objetivo o un agente ejecuta la guía usando solo el texto; cada punto en el que se pregunta algo o se adivina es una carencia del texto, no de quien lo lee.
8. Poner fecha, versión y alcance al principio; eliminar las secciones obsoletas en lugar de dejarlas marcadas como «obsoleto».

Resultado esperado

Menos preguntas que el texto debería haber respondido; guías que los agentes pueden ejecutar solo con el texto; un wiki en el que referencia y explicación se encuentran por separado.

Límites y base de verificación

La comprensibilidad no sustituye a la exhaustividad; en caso de conflicto, prevalece la precisión. Las reglas de escritura siguen la guía citada, y la estructura sigue el modelo Diátaxis; no se mide el efecto sobre los agentes, sino que se propone como método de verificación.