Documenta menos, pero documenta mejor

Documentar es aquello que nos gustaría que alguien hubiera hecho cuando afrontamos un nuevo proyecto de migración de software.

Si crear documentación es tan importante ¿por qué no se documenta más? Si la documentación es útil ¿por qué no crea sistemáticamente?

Hay una explicación: documentar tiene un coste y no siempre es útil.

¿Para qué sirve documentar?

Documentamos para que otras personas entiendan la finalidad del código.

El código se escribe con una finalidad.

La finalidad inmediata es ejecutar una serie de instrucciones en el ordenador. Pero hay una razón de orden superior: la aplicación implementa un caso de uso. Ese caso de uso o proceso de negocio debe ser especificado en la documentación. Si no entendemos el caso de uso ¿cómo vamos a entender el código?

Separación de intereses

No todos los documentos son iguales. En la fase de diseño del nuevo sistema hay dos documentos imprescindibles:

• Business Architecture Design: incluye la especificación del modelo actual, del modelo futuro y el gap fit analysis o análisis de los cambios en los procesos de negocio/IT que se deben realizar.
• System Architecture Design: contiene las especificaciones técnicas del sistema a implementar. Debe contener la arquitectura de aplicaciones, datos y tecnología necesarias para poner en marcha el nuevo sistema.

Este es un punto crítico que te ahorrará mucho tiempo después: si hay cambios en los procesos de negocio, modelízalos por separado. Es lo que en programación se llama separación de intereses. Cuanto más desacoples los dos niveles (Business y IT) más fácil será después controlar cualquier posible cambio en el alcance de los proyectos.

Los desarrolladores ya documentan

Si los equipos de desarrollo escriben código no hace falta que creen documentos formales adicionales. En un proyecto Scrum, la relación de historias de usuario, el código de alto nivel y sus anotaciones deberían ser suficientes para que otro equipo pueda entender el código, mantenerlo y modificarlo.

Si el código no es claro, entonces el problema no está en la documentación. Revisa el código, anótalo, pero no inviertas mucho tiempo en documentos adicionales.

Transición y operación

El momento de la transición es delicado. Los usuarios de los procesos de negocio empiezan a interactuar con el software y todo el mundo repite lo mismo: “Manuales, manuales, manuales”. Luego, van a casa, encienden el ordenador e interactúan con Facebook y Twitter que son aplicaciones para las que nunca nadie ha solicitado un manual.

La reclamación de un manual es un síntoma de que la función Ayuda de tu aplicación no ha sido correctamente incluida en el diseño. Posiblemente el diseño UX no es adecuado. Por lo tanto, ahórrate los manuales y diseña mejor.

En la fase de operación debes documentar los procedimientos de configuración de forma concisa por si hace falta transferirlos a otros equipos, pero el foco deben ser las métricas. Y las métricas impactan en el negocio: deberás tener al menos un documento en el cual Business y IT se pongan de acuerdo en qué métricas hay que controlar.