Xuaps

Papel apilado

Sobre documentar

Los programadores que están en un proyecto siempre piensan que se documenta demasiado, mientras que los programadores que se incorporan al proyecto piensan que hay poca documentación o que es mala.

Yo he trabajado con programadores obsesionados por documentar todo, hacer diagramas, umls, etc. Todo antes de escribir una sóla línea de código. Era divertido ver cómo se les derrumbaba conforme avanzaba el proyecto y como esa ingente cantidad de documentos quedaban obsoletos. No era menos divertido ver a las nuevas incorporaciones devanarse los sesos leyendo esos panfletos que no se correspondían con el código. Siempre estaba también, el que pretendía que las cosas funcionaran como decía la documentación simplemente porque así estaba escrito.

He trabajado en otros proyectos donde la documentación estaba por contrato. Con el proyecto casi acabado todos los programadores nos poníamos a escribir documentación “de prisa y corriendo”.

Y por supuesto también he trabajado en proyectos con poca o nula documentación. Si tuviera que elegir uno de estos optaría por el último, al menos no pierdes el tiempo consultando una referencia enciclopédica para acabar descubriendo que el sistema ya no funciona así.

No documentes para programadores

La documentación es útil para mantener el producto, es útil cuando se incorporan nuevos miembros al equipo y es útil cuando necesitamos saber qué circunstancias fueron clave para implementar una funcionalidad de una u otra forma. Por tanto hay dos tipos de documentación, la que describe el estado final de sistema y la que cuenta la historia del proyecto.

La mejor documentación es la que surge de forma natural en el proceso de desarrollo. En tu proyecto ya estás haciendo ambos tipos de documentación de forma natural porque es imposible no hacerlo. Lo que mejor describe el estado final del sistema es sin duda el código. Y para documentar la historia del proyecto tienes un montón de información, emails, actas de reuniones, oferta comercial, log del repositorio, etc. El problema de ambos tipos es que no se formaliza y por tanto no se cuida o no se hace accesible.

El código es la mejor documentación del estado final del proyecto, los que dicen que es demasiado complejo y que se requiere de una documentación escrita con un mayor nivel de abstracción solo están poniendo un parche al problema. Clean Code, DDD, BDD son mejores soluciones.

La historia del proyecto está en la comunicación entre todos los stakeholders. Hagámoslo todo público, accesible e integrémoslo para poder hacer búsquedas y mostrémoslo en un calendario en forma de historia. Por supuesto hay que ser consciente de que ese mail, ese diagrama que estamos haciendo ahora será público y pasará a formar parte de la historia del proyecto.

Ya estás creando todo esta documentación. ¿De verdad necesitas más? ¿o prefieres darle sentido a todo lo que ya estás generando?

Documenta para tus usuarios

Sin embargo la documentación para tus usuarios es una parte importante de tu producto. Cuanto mejor sea esta documentación mejor será tu producto. Olvídate de autogenerarla o extraerla de los comentarios o poner a tus programadores a escribir un manual. Dale la importancia que tiene y busca personas que sepan comunicar para escribir esta documentación.

Como de costumbre yo no te digo que documentes o que no lo hagas, sólo que hay otras formas de hacerlo y funcionan.