Propongo no documentar

Ya no se recomienda la documentación de los elementos que intervienen en un proyecto fuera del propio elemento.

Unos cuantos miles de los nuevos filósofos/pensadores que han surgido alrededor del proceso de desarrollo de proyectos software están de acuerdo conmigo. Es en serio.

Cada parte de un proyecto (programas, modelos de datos, etc.) debe estar autodocumentada. Si documentamos un elemento fuera de éste... lo más normal es que, pronto, la documentación quede "desalineada" con lo documentado. Fundamentalmente, por lo costoso de mantener dos cosas tan alejadas (la técnica y la documentación) a la vez y alineadas.

Ya ha quedado demostrado empíricamente que la documentación no conlleva ningún beneficio y además tiene un coste importante. Lo que ahora está de moda es la "agilidad" y la documentación no aporta nada en beneficio de esta "agilidad".

Además, a los programadores no nos gusta documentar, es un hecho, así que dejamos esta aburrida tarea siempre para el final (cuando ya nos viene "pisando los talones" un nuevo proyecto mucho más interesante) y por ello no nos la tomamos en serio y la "salvamos" como podemos.

Y ¿qué hay peor que algo no documentado? Algo mal documentado.

La siguiente pregunta refuerza más lo que digo ¿cuántas herramientas de ayuda a la documentación de proyectos software conocéis, de memoria, que mantengan versiones actualizadas y que no estén ancladas en técnicas de los años 80? (no vale decir el word, la excel o el notepad).

Actualmente, casi todos los nuevos lenguajes de programación permiten al programador autodocumentar mientras programa. Parte de esta documentación tiene "coste cero" porque hay herramientas que extraen información del propio código y generan la documentación. Así para que alguien tenga una versión actualizada solo necesita pedirle a la herramienta que se la genere ¿chachi, no?

Lo que creo es que: deberíamos esforzarnos en hacer las cosas lo más sencillas posibles, autodocumentadas/autoentendibles, utilizando "modos" conocidos y aceptados por todos. Que todos tengamos las habilidades suficientes para entender esos "modos" de forma natural (sin depender de otros elementos), que esos "modos" estén escritos (no documentados) en la forma de un reglamento básico (que dice cómo se deben hacer las cosas) y que, además, este reglamento básico se alteré lo menos posible a lo largo del tiempo.

Y, por supuesto, que todos sigamos ese reglamento básico, nos guste mucho o poco, como si fuesen mandamientos divinos (no se cuestionan... se acatan, simplemente).