Documentation & Review — Habilidades

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 <nombre>. 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 <nombre>

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 — <decisión> 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 <pregunta> y entrega. Un documento corto y verificado vale más que uno que parece completo porque rellenó sus huecos.

Descargar .md

README y guía de incorporación

Produce el documento que lee primero quien llega nuevo — y con el que puede trabajar sin preguntar nada que el documento debería haber respondido.

Entregable

Un documento Markdown, readme.md, con la estructura fijada en Salida más abajo. Es la puerta desde la que se alcanza el resto de la documentación del proyecto, y una entrada de Auditoría de documentación.

Entradas obligatorias

Acceso al repositorio — el árbol entero, incluidos los archivos de compilación, dependencias y configuración.
Una máquina donde ejecutar la instalación — cada paso de este documento se ejecuta antes de escribirse.
Para quién es — alguien que acaba de entrar al equipo, alguien de fuera que contribuye, o alguien que vuelve tras mucho tiempo; necesitan cosas distintas.

Sin acceso al repositorio, detente e infórmalo. Sin una máquina donde ejecutar la instalación la guía todavía se puede escribir, pero cada paso queda marcado sin verificar y el documento lo declara arriba.

Entradas opcionales

Quiénes mantienen el proyecto y dónde responden preguntas
El proceso de revisión y contribución, y las reglas de ramas que lo acompañan
Un documento de incorporación existente y las preguntas que no supo responder
Los sistemas operativos soportados y las diferencias entre ellos
Las cuentas, credenciales o accesos que hay que solicitar antes de empezar
Los fallos de instalación conocidos y en qué acaban siendo

Una entrada opcional ausente se convierte en un hueco con nombre en la sección 9, no en una frase plausible. Una guía que adivina qué accesos hacen falta manda a quien llega a la persona equivocada.

Ejecución

1 — Declarar qué es esto y qué no. Dos o tres frases: qué hace el proyecto, quién lo usa y qué cosas cercanas no es. Quien haya entendido mal el propósito leerá mal todas las instrucciones que vengan después.

2 — Tomar los requisitos del proyecto, no de la costumbre. Lee los archivos de dependencias, compilación y configuración y saca de ahí las versiones exigidas. Donde haya una versión fijada, escribe la fijación. Donde se admita un rango, escribe el rango. Una versión tomada de lo que casualmente hay instalado en una máquina es una conjetura con un número encima.

3 — Ejecutar la instalación sobre una copia limpia y anotar lo que hiciste. Cada comando en el orden en que se ejecutó, incluidos los que hicieron falta y no estaban documentados en ninguna parte. Si un paso necesitó un acceso que tú ya tenías, dilo — es un requisito que quien llega todavía no tiene.

4 — Arrancarlo y después probarlo. Registra el comando que arranca el proyecto, qué debe ver el lector cuando funcionó, el comando que ejecuta las pruebas y qué aspecto tiene una ejecución correcta. Quien no pueda distinguir el éxito del silencio seguirá adelante y romperá algo más lejos.

5 — Mapear el árbol. Los directorios que quien llega va a tocar, qué vive en cada uno y dónde va algo nuevo de cada tipo. Salta las partes que nadie edita a mano; aquí solo son ruido.

6 — Escribir las convenciones por las que se le corregiría. Forma del mensaje de commit, nombres de rama, formato, la revisión por la que debe pasar un cambio y lo que el proyecto rechaza automáticamente. Una convención no escrita es una regla que quien llega descubre en la revisión.

7 — Nombrar dónde preguntar. El sitio al que van las preguntas, quién las responde y qué incluir en la pregunta. Después marca sin verificar cada paso que no pudiste ejecutar.

Salida

readme.md, en este orden:

1. Qué es esto — propósito, quién lo usa y qué no es
2. Requisitos previos — por requisito: cuál, la versión que el proyecto exige y el archivo del que se leyó esa versión
3. Accesos y cuentas — qué hay que solicitar antes de empezar y a quién
4. Instalación — comandos numerados, cada uno con su resultado esperado y si se ejecutó
5. Cómo arrancarlo — el comando, la salida esperada y el primer fallo habitual
6. Cómo probarlo — el comando, qué aspecto tiene una ejecución correcta y qué hacer con una fallida
7. Estructura del proyecto — directorio, qué vive ahí y dónde va el trabajo nuevo de ese tipo
8. Convenciones — las reglas contra las que se revisa un cambio
9. Dónde preguntar y qué falta — quién responde y cada paso marcado sin verificar

Validación

El documento está listo cuando se cumple todo esto:

Cada comando de las secciones 4 a 6 se ejecutó, o está marcado sin verificar
Cada versión de la sección 2 cita el archivo del proyecto del que se leyó
La sección 4 parte de una copia limpia y no supone ningún estado previo
Las secciones 5 y 6 declaran cada una qué aspecto tiene el éxito
La sección 1 dice qué no es el proyecto, al menos en una frase
No se nombra ninguna herramienta, servicio ni cuenta sin decirle a quien llega cómo conseguirla

Falla la ejecución si aparece una versión que no se leyó de un archivo del proyecto, o si un comando documentado nunca se ejecutó y no está marcado sin verificar.

Gestión de fallos

Sin acceso al repositorio — detente. Informa de que una incorporación no se puede escribir a partir de la descripción de un proyecto.
La instalación no se puede completar — documenta hasta el paso que falló, registra el fallo con su mensaje exacto, marca los pasos restantes como sin verificar y lista el bloqueo en la sección 9. No escribas los pasos que esperarías que vinieran después.
Pasos manuales no documentados — regístralos como pasos con su propio número, no como una nota al margen. El paso que alguien hace de memoria es el que quien llega no encuentra nunca.
Los requisitos se contradicen entre archivos — registra cada versión con el archivo del que viene, marca el punto como en disputa y elévalo a la sección 9 como bloqueante.
Sin contacto con nombre — escribe desconocido en la sección 9 y declara que quien llega no tiene dónde preguntar. Una guía que termina sin una ruta hacia una persona deja de funcionar la primera vez que se equivoca.

Descargar .md

Redacción de manuales operativos

Produce el procedimiento que alguien sigue bajo presión, de noche, sin contexto y sin nadie a quien preguntar.

Entregable

Un documento Markdown, runbook.md, con la estructura fijada en Salida más abajo. Un manual cubre un procedimiento; un segundo procedimiento lleva un segundo documento.

Entradas obligatorias

El procedimiento — la operación que hay que dejar escrita y la condición que la dispara.
El sistema contra el que se ejecuta — acceso a él, o a alguien que ejecute los pasos mientras tú los registras.
Quién lo va a ejecutar — el rol, y qué le está permitido hacer a ese rol sin pedir permiso.

Si falta cualquiera de los tres, detente e informa de cuál. Un manual escrito sin saber quién lo ejecuta o bien supone accesos que esa persona no tiene, o bien le oculta pasos que necesita.

Entradas opcionales

Incidentes anteriores en los que se usó este procedimiento y qué salió mal
La monitorización, las alertas o los síntomas que indican que este manual aplica
El proceso de cambios y aprobaciones que esta operación debe respetar
Un entorno fuera de producción donde ensayar los pasos
La estructura de escalado, por roles
El registro de auditoría o cumplimiento que esta operación debe dejar

Cuando falta una entrada opcional, el manual lo dice en el punto donde importa: un paso no ensayado se marca sin probar, una ruta de escalado desconocida se escribe desconocido en la sección 7. Nunca se rellena con lo más probable.

Ejecución

1 — Fijar el límite. Cuándo aplica este manual y — igual de importante — cuándo no, nombrando el procedimiento más cercano para los casos que no cubre. Quien sigue con confianza el manual equivocado hace más daño que quien se detiene.

2 — Listar las precondiciones y los accesos. Qué debe ser cierto antes del primer paso y qué permisos, credenciales o aprobaciones necesita tener ya en la mano quien opera. Todo lo que habría que solicitar a mitad del procedimiento es una precondición, no un paso.

3 — Escribir los pasos, cada uno con su verificación. Una acción por paso, en orden, con el comando o el control nombrado exactamente y las partes variables escritas como <nombre>. Debajo de cada uno, cómo confirma quien opera que funcionó. Un paso sin verificación es un paso cuyo fallo se descubre más tarde y por otra vía.

4 — Escribir las bifurcaciones como ramas. Donde el procedimiento se abre, declara la condición observable y qué hacer a cada lado. Ningún paso puede decir según convenga: bajo presión esa frase significa que quien opera está adivinando, y el manual le ha devuelto la decisión a la persona peor situada para tomarla.

5 — Escribir la reversión. Para cada paso que cambia el estado, cómo deshacerlo y si se puede deshacer siquiera. Un paso que no se puede revertir se marca IRREVERSIBLE y lleva su propia confirmación antes de ejecutarse.

6 — Tratar el fallo en el sitio. Debajo de cada paso, qué hacer cuando falla, en lugar de una sola sección al final. Después el escalado: a quién involucrar, por rol y no por nombre, en qué momento y qué contarle.

7 — Ensayar y después marcar lo que no se ensayó. Ejecuta el procedimiento donde sea seguro hacerlo, corrige lo que la ejecución revele y marca sin probar cada paso que no pudiste ejecutar. Registra qué hay que dejar anotado al terminar: horas, decisiones tomadas y el estado en que quedó el sistema.

Salida

runbook.md, en este orden:

1. Alcance — cuándo aplica, cuándo no y a dónde ir en su lugar
2. Precondiciones — qué debe ser cierto y qué accesos necesita quien opera
3. Roles — quién lo ejecuta y a quién hay que avisar de que se está ejecutando
4. Pasos — numerados, una acción cada uno, con la verificación y la respuesta al fallo debajo
5. Bifurcaciones — la condición observable y la rama que se toma en cada caso
6. Reversión — por paso que cambia el estado: cómo deshacerlo, o IRREVERSIBLE
7. Escalado — el disparador, el rol al que acudir y qué entregarle
8. Al terminar — qué registrar, dónde y quién lo revisa
9. Estado del ensayo — qué pasos se ejecutaron, cuáles quedan sin probar y cuándo se ejecutó esto por última vez

Validación

El manual está listo cuando se cumple todo esto:

Cada paso de la sección 4 declara una sola acción y cómo verificarla
Ningún paso contiene según convenga, si hace falta ni ninguna otra instrucción que devuelva la decisión a quien opera
Cada paso que cambia el estado aparece en la sección 6, con su reversión o como IRREVERSIBLE
Cada rama de la sección 5 nombra una condición observable, no un juicio
La sección 7 nombra roles, nunca personas
Cada paso no ejecutado durante el ensayo está marcado sin probar en la sección 9

Falla la ejecución si un paso cambia el estado sin entrada en la sección 6, o si algún paso se escribió sin ejecutarse y sin marcarse sin probar.

Gestión de fallos

Sin acceso al sistema — escribe el procedimiento a partir del material aportado, marca cada paso como sin probar y declara arriba que este manual no se ha ejecutado nunca. Di con claridad que hay que ensayarlo antes de confiar en él.
Un paso no se puede ensayar sin riesgo — márcalo sin probar con el motivo, y escribe la verificación que quien opera debe esperar a partir de la definición del paso y no de una ejecución.
El procedimiento no tiene reversión — dilo en la sección 6 en lugar de dejarla vacía, marca el paso como IRREVERSIBLE y añade la confirmación que quien opera debe hacer antes.
Sin estructura de escalado — escribe desconocido en la sección 7 y lístalo como bloqueante. Un manual que termina en un paso fallido y sin ruta hacia adelante deja tirada a la persona que lo sigue.
Versiones enfrentadas del procedimiento — registra cada una con su fuente, marca el punto como en disputa y no las fundas en una sola secuencia. Un procedimiento fundido que nadie ha ejecutado es peor que dos que alguien sí ha ejecutado.

Descargar .md

Notas de versión y changelog

Convierte un conjunto de cambios integrados en lo que el lector necesita: una entrada para el registro y unas notas para quien sufre el cambio.

Entregable

Un documento Markdown, release-notes.md, con la estructura fijada en Salida más abajo. Lleva las dos formas: la sección 2 es la entrada que se añade al changelog del proyecto, y de la sección 4 en adelante es lo que se publica a los lectores.

Entradas obligatorias

El conjunto de cambios integrados — los commits, fusiones o tickets incluidos en esta entrega, y el límite dentro del que caben.
El identificador de versión — cómo se llama esta entrega, aportado por quien nombra las versiones aquí. Nunca se inventa.
El lector — a quién se publican las notas: quienes ejecutan el software, quienes integran contra él, o ambos.

Si falta el conjunto de cambios o el identificador de versión, detente e infórmalo. Unas notas montadas desde el recuerdo de lo que se estuvo haciendo omitirán exactamente el cambio que le rompe algo a alguien.

Entradas opcionales

Los tickets o incidencias que cierran los cambios, y qué decían
Las notas de la entrega anterior, para mantener la terminología
Pasos de migración ya escritos por quienes hicieron el cambio
Decisiones de obsolescencia y la fecha prevista de retirada
Mediciones tomadas antes y después de un cambio de rendimiento
El canal donde se publican las notas y los límites de longitud que impone

Las entradas opcionales ausentes reducen lo que las notas pueden afirmar. Sin mediciones se describe el cambio pero nunca se llama más rápido; sin fecha de retirada una obsolescencia se registra como prevista con desconocido al lado.

Ejecución

1 — Tomar el conjunto de cambios del registro, no del recuerdo. Lista cada cambio integrado dentro del límite. Cada entrada de la salida se traza hasta uno de ellos, y un cambio que llega a la salida sin nada detrás se elimina.

2 — Ordenar por lo que es. Añadido, cambiado, corregido, eliminado, seguridad. Ordena por el efecto sobre el lector y no por el componente que se tocó: el lector busca qué le ha pasado a él, no en qué módulo ocurrió.

3 — Separar lo visible de lo interno. Un cambio que el lector puede observar va a las notas. Una refactorización, una prueba o un cambio de compilación se registra como interno y se queda fuera de la sección del lector. Disfrazar un cambio interno de mejora visible es como unas notas de versión pierden a sus lectores.

4 — Subir los cambios incompatibles al principio. Todo lo que deja de funcionar, cambia de forma o exige una acción va arriba del todo, con la acción detallada. Un paso de migración enterrado bajo una lista de novedades es un paso de migración que se va a pasar por alto.

5 — Escribir cada entrada como su efecto. Declara qué es distinto para el lector y qué debe hacer al respecto, no qué función se editó. Cuando una entrada tenga un ticket o un cambio detrás, cítalo para que el lector pueda llegar más lejos.

6 — Afirmar solo lo que se midió. Un cambio solo se puede llamar más rápido, más pequeño o más fiable si hay una medición detrás. Sin ella, describe qué cambió y deja el juicio al lector.

7 — Registrar las obsolescencias y lo que viene. Qué queda obsoleto, qué lo sustituye y cuándo se retirará — desconocido donde no se haya decidido una fecha. Después contrasta cada entrada con el conjunto de cambios una última vez.

Salida

release-notes.md, en este orden:

1. Identidad de la entrega — el identificador tal como se aportó, la fecha y el límite del conjunto de cambios
2. Entrada de changelog — agrupada en Añadido, Cambiado, Corregido, Eliminado, Seguridad; una línea por cambio, cada una citando de dónde sale
3. Cambios internos — cambios sin efecto visible para el lector, registrados y fuera de la sección 4
4. Cambios incompatibles y acción necesaria — qué deja de funcionar y los pasos exactos a dar; vacía solo si no hay ninguno, y lo declara
5. Novedades — por entrada: el efecto sobre el lector y qué puede hacer ahora
6. Correcciones — el síntoma que el lector habría visto, y que ya no está
7. Obsolescencias — qué queda obsoleto, su sustituto y la fecha de retirada o desconocido
8. Afirmaciones sin verificar — todo lo afirmado sin una medición ni un cambio trazable, listado en lugar de publicado

Validación

El documento está listo cuando se cumple todo esto:

Cada entrada de las secciones 2 y 4 a 7 se traza hasta un cambio del conjunto de entrada
Cada cambio del conjunto de entrada aparece una vez, en la sección 2 o en la 3
La sección 4 va antes de la 5 y enuncia sus pasos como acciones que el lector ejecuta
Ninguna entrada afirma una mejora medible sin una medición aportada
El identificador de la sección 1 es el que se aportó, sin cambios
La sección 3 se usa para el trabajo interno en lugar de dejarlo fuera

Falla la ejecución si una entrada de la salida no se traza a ningún cambio de la entrada, o si se afirma una mejora sin medición detrás.

Gestión de fallos

Sin conjunto de cambios — detente. Informa de que unas notas de versión no se reconstruyen a partir de lo que la gente recuerda haber hecho.
Sin identificador de versión — produce el documento con la sección 1 marcada como VERSIÓN SIN ASIGNAR y nombra a quién le toca asignarla. No inventes un identificador ni incrementes el anterior.
El efecto de un cambio sobre el lector no está claro — lístalo en la sección 8 con la pregunta y pregúntale a quien lo hizo. No lo describas en vago para rellenar una línea.
Un cambio incompatible sin ruta de migración — regístralo en la sección 4, declara con claridad que no hay migración disponible y elévalo como bloqueante de la entrega. Un cambio incompatible sin ruta es una decisión, no una nota.
Conjunto de cambios parcial — produce el documento para el rango conocido, declara el límite en la sección 1 y márcalo como INCOMPLETO — cubre solo <rango>.

Descargar .md

Auditoría de documentación

Lee un conjunto de documentación contra el sistema que describe e informa de cada punto en el que ambos discrepan.

Entregable

Un documento Markdown, documentation-audit.md, con la estructura fijada en Salida más abajo. Sus hallazgos son la entrada de Redacción de documentación técnica y de la corrección de cada documento que nombra.

Entradas obligatorias

El conjunto de documentación — los documentos dentro del alcance y dónde vive cada uno.
El sistema que describen — acceso de lectura al código, la configuración y las interfaces sobre las que los documentos afirman cosas.
El lector al que sirve el conjunto — la auditoría informa de lo que falta, y lo que falta solo tiene sentido frente a un lector.

Sin los documentos y sin el sistema, detente e informa de cuál falta. La documentación no se puede auditar contra sí misma; un conjunto puede ser coherente por dentro y estar equivocado entero.

Entradas opcionales

Un entorno donde se puedan ejecutar los comandos documentados
La historia del sistema, para distinguir un comportamiento retirado de uno que nunca existió
Las preguntas que los lectores hacen de verdad al soporte
El dueño de cada documento, para que los hallazgos tengan a dónde ir
Auditorías anteriores, y cuáles de sus hallazgos se aceptaron
La entrega respecto a la que los documentos deberían estar al día

Sin un entorno, los ejemplos se comprueban leyendo en lugar de ejecutando, y cada hallazgo así se marca comprobado leyendo para que nadie lo dé por probado. Los dueños ausentes se registran como desconocido, no se asignan.

Ejecución

1 — Inventariar el conjunto. Cada documento dentro del alcance: dónde vive, qué dice cubrir, quién lo posee y cuándo cambió por última vez. Un documento que nadie nombró lo sigue leyendo alguien, así que recorre el árbol en lugar de trabajar con la lista que te dieron.

2 — Extraer las afirmaciones comprobables. De cada documento, cada afirmación que el sistema puede confirmar o contradecir: comandos, rutas, parámetros, nombres de opciones, valores por defecto, secuencias y comportamientos declarados. Las opiniones y los razonamientos no son comprobables y no se auditan aquí.

3 — Comprobar cada afirmación contra el sistema. Para cada una, encuentra el código o la configuración que la zanja. Registra juntas la ubicación en el documento y la ubicación en el sistema; un hallazgo que solo cita el documento es una opinión, y quien escribió el documento la tratará como tal.

4 — Ejecutar lo que se pueda ejecutar. Ejecuta los comandos y los ejemplos documentados en un entorno seguro y registra qué ocurrió. Donde no se pueda ejecutar nada, marca el hallazgo como comprobado leyendo y dilo en el informe, no en una nota al pie.

5 — Clasificar lo encontrado. Una afirmación contradicha por el sistema, un comando o una ruta que ya no existe, un ejemplo que fallaría, un comportamiento retirado que se sigue documentando y un comportamiento que existe y no está documentado en ninguna parte. Cada uno es una reparación distinta, así que cada uno lleva su propia lista.

6 — Encontrar lo que le falta al lector. Recorre la tarea que el lector debe completar y marca cada punto en el que tendría que adivinar, leer el código o preguntar a alguien. Un paso no documentado es un hallazgo aunque todo lo escrito sea correcto.

7 — Ordenar por el coste de creerlo. Ordena los hallazgos por lo que le ocurre a quien se fía de la afirmación equivocada — datos perdidos, accesos concedidos, tiempo tirado — y no por lo fácil que sea arreglarlo. Después registra qué quedó sin cubrir.

Salida

documentation-audit.md, en este orden:

1. Alcance y fecha — los documentos auditados, el estado del sistema contra el que se comprobaron y cuándo
2. Método — qué se ejecutó, qué se comprobó leyendo y qué no se comprobó en absoluto
3. Afirmaciones contradichas — por hallazgo: la ubicación en el documento, la afirmación, la ubicación en el sistema y qué es cierto en realidad
4. Procedimientos rotos — comandos, rutas o pasos que ya no existen, cada uno con su ubicación en el documento
5. Ejemplos que fallan — el ejemplo, dónde está y qué ocurrió al ejecutarlo o por qué fallaría
6. Comportamiento retirado aún documentado — qué se describe y la evidencia de que ya no está
7. Comportamiento sin documentar — qué existe, dónde y qué lector lo necesita
8. Huecos para el lector — el punto de la tarea en el que el lector tendría que adivinar, y qué necesita
9. Hallazgos por coste — cada hallazgo ordenado por la consecuencia de creerlo, con un dueño o desconocido
10. Sin cubrir — documentos o afirmaciones que la auditoría no pudo comprobar, y por qué

Validación

El informe está listo cuando se cumple todo esto:

Cada hallazgo de las secciones 3 a 7 cita una ubicación en el documento y una en el sistema
Cada hallazgo está marcado como ejecutado o como comprobado leyendo
La sección 9 contiene todos los hallazgos de las secciones 3 a 8, ordenados por consecuencia
Ningún hallazgo propone reescribir algo sin nombrar la afirmación que está mal
La sección 10 no está vacía, o declara explícitamente que se comprobó el conjunto entero
No aparece ninguna afirmación sobre el sistema que no se haya leído del sistema

Falla la ejecución si un hallazgo cita un documento sin citar la ubicación del sistema que lo contradice, o si se asigna una gravedad sin declarar la consecuencia que la sostiene.

Gestión de fallos

Sin acceso al sistema — detente. Informa de que una auditoría sin el sistema compara documentos entre sí, y eso es corrección de estilo, no una auditoría.
Sin entorno donde ejecutar — audita leyendo, marca cada hallazgo como comprobado leyendo y declara en la sección 2 que no se ejecutó nada.
El sistema está a mitad de un cambio — audita contra un estado con nombre, regístralo en la sección 1 y marca como pendiente de <cambio> los hallazgos que ese cambio en curso resolvería.
Un documento sin dueño — registra desconocido en la sección 9 y lístalo en la sección 10. Un documento sin dueño acumula hallazgos y no se le arregla ninguno.
El conjunto es demasiado grande para cubrirlo — audita primero los documentos de la tarea principal del lector, declara el límite en la sección 1, lista el resto en la sección 10 como sin cubrir y marca el informe como PARCIAL.

Descargar .md