# Redacción de documentación técnica Produce un documento escrito para un lector concreto y una tarea concreta — con cada afirmación comprobada contra el sistema en lugar de recordada. ## Entregable Un documento Markdown, `technical-document.md`, con la estructura fijada en **Salida** más abajo. Es la entrada de **Auditoría de documentación** cada vez que cambia el sistema que describe. ## Entradas obligatorias - **El tema** — el sistema, componente o procedimiento que hay que documentar, con acceso a él o al material que lo describe. - **El lector** — para quién es el documento y qué conocimiento tiene ya. - **La tarea** — qué debe poder hacer ese lector cuando termine de leerlo. Si falta cualquiera de los tres, detente e informa de cuál. Un documento escrito sin lector y sin tarea con nombre está escrito para nadie, y se nota. ## Entradas opcionales - Acceso al repositorio, esquemas, definiciones de interfaz, archivos de configuración - Un documento existente sobre el mismo tema y qué falla en él - El lugar de publicación y el formato que impone - Una lista de terminología o un estilo de casa que el documento deba seguir - Una persona revisora que pueda confirmar las afirmaciones técnicas - Las preguntas de soporte que el documento debe hacer desaparecer Cada entrada opcional que falte estrecha lo que se puede verificar, no lo que se afirma. Cuando falta una, las afirmaciones afectadas se marcan `sin verificar` y se listan en **Preguntas abiertas**. ## Ejecución **1 — Decidir el tipo de documento.** Una explicación, un cómo-hacerlo, una referencia y un tutorial responden preguntas distintas y se leen en estados distintos. Elige uno y escribe su nombre arriba. Mezclarlos es el motivo más común de que la documentación falle: a quien necesita un comando se le hace leer un razonamiento, y a quien necesita el razonamiento se le entrega un comando. **2 — Nombrar el conocimiento de partida.** Deja escrito qué se supone que el lector sabe antes de la primera línea y qué no. Una suposición callada es un lector atascado en el paso uno, sin forma de saber si lo que está mal es el documento o su propio entorno. **3 — Reunir y verificar los hechos.** Toma cada afirmación del código, de la configuración o del sistema en marcha — no de la memoria ni de un documento anterior. Registra dónde se comprobó cada una. Una afirmación que no se pudo comprobar contra nada se marca `sin verificar` en el borrador; nunca se enuncia sin más. **4 — Redactar con la forma del tipo elegido.** Un cómo-hacerlo es una secuencia ordenada hacia un único resultado. Una referencia es exhaustiva y se consulta en lugar de leerse. Una explicación da motivos y renuncias. Un tutorial es un camino ensayado que funciona de principio a fin para quien empieza. Escribe lo que el tipo elegido exige y deja el resto a otros documentos. **5 — Hacer ejecutable cada instrucción.** Cada comando, ruta, parámetro y nombre de archivo aparece exactamente como debe teclearse, con las partes variables escritas como ``. Cada paso dice qué debe ver el lector cuando ha funcionado, para que un fallo se detecte donde ocurre y no tres pasos después. **6 — Quitar lo que el lector no necesita.** Elimina la historia, la disculpa y el razonamiento que pertenece a una explicación. La medida no es la longitud — un lector que tenga que hojear para llegar a la instrucción la pasará de largo. **7 — Reunir lo que no se pudo verificar.** Cada afirmación sin verificar, cada pregunta que el material no pudo responder, y quién puede zanjarla. ## Salida `technical-document.md`, en este orden: - **1. Título y tipo** — el tema, y cuál de los cuatro tipos es este documento - **2. Lector y tarea** — para quién es y qué podrá hacer tras leerlo - **3. Conocimiento previo** — qué debe saber ya el lector y qué queda fuera - **4. Cuerpo** — las secciones que exige el tipo elegido, en el orden que el lector necesita - **5. Notas de verificación** — por grupo de afirmaciones: dónde se comprobó, o `sin verificar` - **6. Documentos relacionados** — qué leer antes de este y qué leer después - **7. Preguntas abiertas** — qué no se pudo verificar y quién puede zanjarlo ## Validación El documento está listo cuando se cumple todo esto: - La sección 1 nombra exactamente un tipo de documento, y el cuerpo se ciñe a él - La sección 2 nombra un lector y una tarea, no un área temática - Cada comando, ruta y parámetro de la sección 4 se tomó del sistema, no de la memoria - Cada paso de un procedimiento declara cómo sabe el lector que funcionó - Cada afirmación que no se pudo comprobar está marcada `sin verificar` en la sección 5 - Ningún marcador del cuerpo queda como contenido de ejemplo; los marcadores dicen `` Falla la ejecución si el cuerpo mezcla dos tipos de documento, o si alguna afirmación se presenta como hecho sin una entrada de verificación detrás. ## Gestión de fallos - **No hay lector ni tarea** — detente. Informa de cuál falta. No elijas un lector: un lector supuesto produce un documento que no le sirve a nadie. - **Sin acceso al sistema** — escribe solo a partir del material aportado, marca cada afirmación como `sin verificar` en la sección 5 y declara arriba que nada se comprobó contra un sistema en marcha. - **Las fuentes se contradicen** — registra ambas afirmaciones con ambas fuentes, marca el punto como `en disputa` y elévalo a la sección 7. No lo zanjes quedándote con la más reciente. - **El tema todavía está cambiando** — documenta la parte asentada, marca el resto como `pendiente — ` y nombra la decisión que lo desbloquearía. - **Material parcial** — produce cada sección que el material sostenga, marca el resto como `INCOMPLETO — pendiente de ` y entrega. Un documento corto y verificado vale más que uno que parece completo porque rellenó sus huecos.