Cuando alguien recibe un sistema que no conoce, el impulso es documentarlo entero. Ese impulso produce, casi siempre, doscientas páginas que nadie lee y que quedan desactualizadas en dos meses.
Documentar bien un sistema heredado consiste sobre todo en decidir qué no documentar.
El orden que funciona
1. Cómo se pone en marcha
Antes que nada: cómo se levanta el sistema desde cero y cómo se lleva un cambio a producción. Es lo que más se necesita, lo que menos suele estar escrito y lo que se olvida más rápido.
La prueba de que está bien escrito: alguien que no lo ha hecho nunca lo consigue siguiendo el documento, sin preguntar.
2. Los flujos que mueven dinero
No todo el sistema importa igual. Facturar, cobrar, liquidar y reportar a una entidad de control importan mucho más que la pantalla de configuración.
De esos flujos conviene escribir qué entra, qué sale, dónde se guarda y qué pasa cuando falla a la mitad.
3. Lo que sorprende
Todo sistema viejo tiene comportamientos que no se deducen del código: la tabla que parece obsoleta y en realidad la lee un proceso nocturno, el campo cuyo nombre no corresponde a lo que guarda, el módulo que se dejó de usar en 2021 pero sigue activo.
Esto es lo más valioso y lo más frágil, porque vive solo en la cabeza de quien lo descubrió. Se anota el mismo día que se descubre o se pierde.
4. El mapa, al final
Un diagrama de qué habla con qué. Se hace al final porque hasta entonces sería una suposición.
Qué no escribir nunca
- Lo que el código ya dice. Una lista de todas las funciones con su descripción es trabajo que se desactualiza al día siguiente y que se puede leer del propio código.
- Lo que se puede consultar. El esquema de la base de datos no se transcribe: se apunta cómo consultarlo.
- Procesos que van a cambiar la semana que viene.
Dónde ponerlo
La documentación que sobrevive es la que vive cerca del código, en el mismo repositorio, y se actualiza en el mismo cambio que modifica el comportamiento. La que vive en una carpeta compartida se muere sola.
La regla que la mantiene viva
Una sola: cuando alguien tenga que preguntar algo que no está escrito, la respuesta se escribe. No al final del proyecto: en ese momento.
Un sistema documentado así crece hacia lo que la gente realmente necesita saber, en vez de hacia lo que alguien imaginó que haría falta. Y es lo que convierte un sistema intocable en uno mantenible, que es de lo que hablamos en cómo rescatar un sistema abandonado.