Una y otra vez aparece el tema de la documentación, durante y después de los proyectos. ¿Qué documentación deberíamos crear? ¿Por qué necesitamos documentos de diseño? ¿Cómo podemos asegurarnos de estar construyendo el software indicado si no tenemos un Documento de Diseño Funcional? Y si el Documento de Diseño Funcional no está alineado con el software que se está construyendo, ¿cómo podemos comprobar que obtenemos lo que pagamos? Y más...
De todas formas, ¿cuál es el problema?
La pregunta más importante que se hace es:
Si no documentamos todo, ¿cómo vamos a saber lo que queremos de antemano, y cómo podemos verificar que obtuvimos lo que necesitamos después de hacer el proyecto?
Por supuesto, esta pregunta ya traeuna respuesta implícita:
Si documentamos cada aspecto del proyecto, vamos a saber lo que hay que construir antes de empezar el trabajo, y así podemos verificar con facilidad si el producto entregado cumple con los requerimientos originales.
El problema es que la respuesta ya estaba implícita en la pregunta!
Tipos de documentación
En mi opinión hay dos tipos de documentos que viven en el mundo de los proyectos de software. No más, no menos.
- Documentación que los miembros del equipo necesitan para trabajar en el proyecto.
- Documentación para ser entregada con el producto final.
Exploremos juntos estos dos tipos de documentos, viendo qué necesita crearse, cuando y en qué profundidad.
Documentación necesaria para que el equipo trabaje en el proyecto
En un mundo ideal nos gustaría que nos dieran el trabajo de una persona a otra mediante comunicación directa: hablando entre las personas, preferentemente en la misma habitación. Sin embargo hay muchas situaciones donde es más conveniente o mejor hacer documentos. Sea porque tenemos que transportar este conocimiento en tiempo y espacio, porque tendemos a olvidarnos de las cosas, o porque escribir nos ayuda a pensar en el proceso.
Sin embargo, en algún punto la industria del sofwtare empezó a confundir estos tipos de documentos de trabajo con documentos que deberían entregarse con el producto. De ahí esa sensación extraña de que los documentos funcionales y de diseño técnico deben estar alineados con el producto desarrollado después de terminar el proyecto. Cuando se les pregunta a las personas porqué querrían hacer esto, las respuestas más comunes incluyen argumentos como:
- Necesitamos saber lo que construimos.
- Por motivos de mantenimiento.
- Cuando algo parezca no funcionar, necesitamos ver qué debía hacer originalmente.
Todas estas razones son malos motivos para intentar mantener documentos enormes que fueron creados con el único propósito de comunicar lo que había que construir. Después de terminar una característica y entregarla al entorno productivo, cualquier documento que se creó durante el proceso de construcción con la intención de soportar este proceso se vuelve obsoleto!
¿Cómo sabemos lo que se construyó?
Simple, mirando al producto en el entorno productivo.
¿Cómo podemos hacer mantenimiento sin documentación?
Cualquier documento que se necesite para el mantenimiento debería crearse como parte del producto entregable. Sin embargo esto no es lo mismo que un documento de diseño. La mayoría del software no tiene una vida tan larga (el software de 5 años ya es bastante viejo), y los lenguajes de programación modernos permiten crear software legible por humanos, disminuyendo así la necesidad de crear documentos separados (el código es gran parte de la documentación). Lo importate aquí es determinar qué tipo de documentos se nececitan realmente para hacer el mantenimiento. En general bastan unos pocos diagramas de arquitectura y de tablas que se usan, pero la mayoría del texto escrito descriptivo (¡nunca!) se lee.
¿Cómo podemos saber lo que se quería originalmente?
Bueno... hoy eso ya no es importante, no? Cuando tenemos un producto que está siendo usado en el entorno productivo, la única pregunta relevante es: ¿Este software satisface nuestras necesidades? Si no, lo que necesitamos hacer es agregar o cambiar algo del producto existente. Cualquier debate sobre la intención original es una pérdida de tiempo.
Aparentemente los seres humanos tenemos esta extraña necesidad de que otros nos digan que estábamos en lo cierto, antes de movernos a la parte donde empezamos a trabajar en la solución. Resulta muy liberador dejar atrás esta necesidad y avanzar directamente a la pregunta principal: ¿tenemos que hacer algún cambio al sistema?
Ni bien podamos aceptar que los documentos que se escriben para soportar el proceso de creación del producto se pueden eliminar ni bien termina el proyecto, vamos a poder enfrentar la absurda necesidad de escribir estos documentos de forma 100% correcta. Es por esto que escribir documentos resulta una tarea que consume tanto tiempo (y por lo tanto es costosa). Una vez que aceptemos que sólo hay que escribir lo necesario para transmitir el mensaje o para ayudarnos a no olvidar algo, vamos a entender que el lapiz y papel, las fotografías de pizarrones, los garabatos, los post-it, etc, todos estos elementos sirven para el propósito!
Documentación que se entrega con el producto
Dependiendo del producto, el cliente, etc, va a haber distintas necesidades sobre la cantidad de documentación a entregar como parte integral del producto. Ejemplos comunes incluyen:
- Manuales de usuario
- Manuales de despliegue
- Manuales de mantenimiento (orientados a la operación del software)
- Documentación técnica (orientados al mantenimiento del código)
El tipo de documentación a entregar con el producto tiene que definirse mucho antes de terminar el producto. Después de todo, el producto no está completo antes de que todas sus partes se marquen como terminadas. Usualmente necesitamos acordar qué documentos entregar con el producto antes de empezar a construirlo (especialmente en una relación cliente-proveedor).
Cuando hayamos acordado qué documentos vamos a entregar con el producto, todavía podemos ser creativos con el formato de esta documentación. Podemos escribir manuales largos, o usar técnicas más "2.0" como captura de video para cumplir con la documentación. Esto último suele ser más barato (estadísticamente cerca de 10 veces más barato!) y además es más probable que se use.
Sin importar el tipo de documentos que se escriban en tu proyecto, hay que dejar de confundir los documentos que se necesitan para soportar el proceso de aquellos que son una parte integral del producto final.
