Esto es algo que escucho con frecuencia: yo no hago documentación en el software que desarrollo (algunos, lo dicen con orgullo, pues aseguran que sus desarrollos son exitosos así).

Son muchas razones expuestas, que podemos resumir en lo siguiente:

• La documentación no sirve para nada y solo nos quita tiempo
• El cliente no la pidió, ¿para qué la hacemos?
• Lo importante es el código, haremos documentación si nos sobra tiempo
• Es demasiado trabajo y son muchos documentos por hacer

Documentar es parte del trabajo del software, es algo que ya debes saber. Estoy de acuerdo que el código es documentación, sin embargo es insuficiente. Antes de hablarte de mis recomendaciones, quiero recordarte dos cosas.

El sistema no te pertenece

Eres el desarrollador principal o parte del equipo que construye el software. Tú escribes el código, lo pones en producción y le das mantenimiento. Aunque la gente se mantenga mucho tiempo, el sistema no les pertenece.

Esta es una razón que escuché muchas veces: “nosotros hicimos el código y nadie más lo modificará; nos entendemos bien y no cambiaremos de integrantes nunca, ¿para qué hacemos documentación?”. Es una razón que parece muy sólida, pero están asumiendo que los únicos dueños del sistema son ellos, lo cual es falso.

Mucha de la información que es necesaria para entender el sistema no está en el código, por lo tanto, necesita estar registrada en alguna parte, debe ser accesible y comprensible por todos.

El software siempre debe desarrollarse con la idea de que no volveremos a meterle mano, que esto lo hará alguien más, así que debemos facilitarle la existencia. Esto es particularmente cierto en proyectos donde la operación del software se traslada a otro equipo (como en los proyectos outsource y proyectos cerrados); la propiedad del software cambia de manos, y los nuevos propietarios (temporales) deben ser capaces de entender y manipular el sistema por su cuenta.

Los extremos son malos

Es igual de malo documentar todo a alto detalle como no documentar. En el primer caso, porque la información importante quedará sepultada entre miles de elementos y será difícil de acceder; en el segundo, porque encontrar y comprender las decisiones tomadas será lento y costoso.

Aristóteles decía “la virtud está en el punto medio”, así que nos basaremos en este principio de Disciplined Agile: documentación mínima, pero suficiente.

La documentación no es un fin

Algunos métodos de trabajo, como RUP y Waterfall, prescriben actividades en los que se involucran un gran número de artefactos: diagramas, descripciones, especificaciones, manuales, listados, etc. Sin embargo, esto se pueden malinterpretar como una obligación, que es lo que hacen muchos equipos y organizaciones. La documentación se convierte en el proyecto:

• El trabajo es guiado por la creación de documentos
• El progreso es medido mediante los documentos producidos
• La comunicación se basa en el intercambio de documentos, que al final no son empleados para la producción del sistema

Es natural que los desarrolladores sientan frustración de hacer algo que no tendrá uso, y que eso los aleje de escribir el código.

Trabajé en organizaciones así, donde los procesos obligaban a producir muchos documentos (algunos duplicaban información) y la mayor parte de mi tiempo transcurría haciéndolos y arreglándolos. Esta información solo se hacía para complacer al equipo de procesos, pero no se usaba en el proyecto. En otras empresas, se hacían especificaciones, que al validarse en documentos la primera vez, todo era aceptado, sin embargo antes de iniciar el desarrollo había que cambiar muchas cosas para ajustar la arquitectura o el producto desarrollado no se aceptaba a pesar de que cumplía con la especificación. A partir de ahí, las modificaciones se hacían directamente en el código y nunca se volvía a actualizar la documentación.

Créeme, todas esas experiencias me han causado renuencia y aversión hacia la documentación, pero solo a la mala documentación. Aún estoy convencido de que es un elemento importante de mi trabajo y que es necesaria en todo producto de software. Claro está, debe hacerse con inteligencia y con un enfoque de utilidad. De eso quiero hablarte en la siguiente entrega.

¡Nos vemos pronto!