Documentar, de manera ágil, pero documentar

Desde hace un tiempo llevo escuchando en varias empresas una curiosa frase, que viene a ser algo así como… “nosotros pensábamos que no necesitábamos documentar nada, porque utilizábamos metodologías ágiles” (frase que se acompaña normalmente de las palabras SCRUM y/o XP), y que continua con “pero el sistema fue creciendo y hemos perdido el control” (control se acompaña de “se fue un desarrollador y no sabemos como hizo parte del sistema”, o de “tenemos parte del desarrollo externalizado a una empresa y no sabemos que han hecho, por lo que no podemos prescindir de ellos”, o de “integramos nuestro software con el de otra empresa, y no sabemos donde acaba un producto y empieza el otro”, etc.)
Los que leéis desde hace tiempo este blog sabéis que uno de sus objetivos, y tema recurrente, es evitar que modas superficiales sustituyan la base de ingeniería del desarrollo software, evitar que importantes errores en la gestión de proyectos software se sigan repitiendo, separar lo esencial de lo accidental, y, en definitiva, intentar ayudar en algo que sucede mucho en nuestra profesión: se empieza a correr la voz sobre una supuesta buena práctica que arregla todos los males, esta se empieza a usar sin control, y con el tiempo el proyecto acaba en alguno de los errores típicos del desarrollo software.
En este caso, la moda es la de “no documentar nada”. Recuerdo que hasta principios del 2000 la moda era documentar el diseño del software haciendo, literalmente, enciclopedias (que nadie leía y mucho menos se mantenían, yo participé en alguna de estas “enciclopedias”), y de ahí, en los últimos años, se ha puesto de moda el no documentar nada. Y, cómo suele suceder, ni blanco, ni negro, en el punto medio está la virtud, o lo que algunos llaman la documentación ágil.
Y a este respecto, me ha parecido muy ajustado al tema un artículo que apareció en la IEEE Software de noviembre – diciembre de 2009, de Bran Selic, titulado “Agile Documentation, Anyone?”, el cual se podría matizar en algún punto, artículo quizás algo polémico, y que a continuación resumo y traduzco:
Frecuentemente escucho a los desarrolladores decir que no les gusta documentar, que no lo encuentran útil, pero… ¿No era el objetivo principal de documentar el ayudar a otros? ¿Cómo es posible una visión tan distorsionada de la documentación? Incluso escucho a los desarrolladores enorgullecerse del «no documentes». Punto de vista que refleja el tan elogiado Manifiesto Ágil, que proclama: «software que funcione, por encima de documentación exhaustiva», como si fueran necesariamente excluyentes entre sí.
El propósito de la documentación es enseñar a quienes no están familiarizados con un sistema cómo este se estructura, funciona y los motivos que llevaron a decidirse por ese diseño. Los principales usuarios de la documentación de diseño son los futuros responsables del mantenimiento del sistema. La única alternativa a no tener documentación de diseño es explorar directamente el sistema, buscar un camino a través de una selva sin mapa ni brújula. Tarea difícil, incluso cuando los autores del diseño están disponibles para hacer de guías. También ineficaz, ya que estos autores tienen que explicar el diseño una y otra vez. Así, mientras que documentar tiene un coste, la inversión, si se hace correctamente, vale la pena.
Pero, sin embargo, en la práctica, la tendencia parece que va en la dirección opuesta. La razón que se argumenta es la dificultad de mantener la documentación sincronizada con algo tan dinámico como es el software, y que el coste de documentar se podría utilizar en generar más código (“software que funcione, por encima de documentación exhaustiva»). Por último, hay quienes argumentan que el código es la única documentación, que es el único que contiene la realidad.
La industria del software está repleta de historias sobre viejo código heredado que nadie se atreve a tocar, porque nadie lo entiende. La semántica de los lenguajes de programación está muy lejos de la semántica del dominio de aplicación. La amplitud de esta brecha es la razón por la que todavía se necesitan programadores.
La preferencia del Manifiesto Ágil por el código por encima de la documentación, sólo se opone a una categoría específica de documentación de diseño: los documentos voluminosos y detallados que describen implementaciones, previas a comprender el problema o tener experiencia con la solución. Los documentos de este tipo se vuelven rápidamente obsoletos, y gran parte del esfuerzo invertido en la producción y actualización de ellos se pierde. Como señaló Helmuth von Moltke: «Ningún plan sobrevive al primer contacto con el enemigo.»
Sin embargo, la ineficacia de los primeros documentos de diseño, no es argumento para su eliminación. En el desarrollo ágil se llega a la comprensión mediante la experimentación con el sistema software, sin duda una de las maneras más efectivas de aprender. Sin embargo, esta manera de aprender sólo está disponible para los diseñadores que crearon el diseño, y no para aquellos que les seguirán y que no han podido participar directamente en la creación del diseño.
Documentar el software en el código es imprudente, redunda en la pesadilla de intentar mantener la duplicación de información coherente. Necesitamos documentos de diseño a un mayor nivel de abstracción, sin detalles tecnológicos innecesarios y estrechamente asociados a conceptos del domino y los requisitos. Estos documentos no sólo ayudan a ver el bosque que se oculta en el mar de código, también a documentar los principios básicos del diseño y a servir como el principal medio de comunicación entre los actores del sistema. Con la excepción de los sistemas relativamente pequeños, llevar el diseño de alto nivel en el código (como recomienda, por ejemplo, Extreme Programming) es imprudente.
Debiera haber documentación de diseño ágil, que mantenga y enlace el diseño y la codificación. Y el esfuerzo realizado en documentar debiera ser proporcional al tamaño del diseño.
Twitter: http://twitter.com/jgarzas

• Acerca de
• Últimas entradas

jgarzas

Ph.D. en informática, Postdoctorado en la Carnegie Mellon (EE.UU) e Ingeniero en Informática.

Primera vez que me tocó hacer una gestión Ágil en una empresa... año 2001. Desde entonces he trabajado en, o para, más de 90. Y he formado a más de 2000 alumnos.

También soy profe de la Universidad Rey Juan Carlos.

Últimas entradas de jgarzas (ver todo)

• Las 3 matrices de priorización Ágil - 19 octubre, 2023
• Etapas del Agile Product Management - 12 octubre, 2023
• Agile Product Management: DINÁMICA «Árbol Solución Oportunidad» + «Valores Esperados» - 5 octubre, 2023