search
top

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

12 Respuestas to “Documentar, de manera ágil, pero documentar

  1. Joserra dice:

    Siempre se olvida la última linea del manifiesto:
    That is, while there is value in the items on
    the right, we value the items on the left more.

    O sea, que nunca el manifiesto dijo que la documentación no tenga valor. Como bien dices lo dificil es quedarse en la medida justa. Ahí cada equipo debe llegar a encontrar el equilibrio, y en unos proyectos será demasiado, y en otros demasiado poco.

    Un saludo

  2. leonardo dice:

    Está muy bueno el documento

  3. Fernando dice:

    podrian poner una opcion de impresion de los documentos. gracias.

  4. Julio dice:

    Se están mezclando muchos problemas como si la documentación fuera su solución, cuando está más que probado que la documentación es otro problema más y que soluciona poco o nada en la mayoría de los casos.

    El problema del código legacy no se soluciona con documentación ya que la documentación es legacy igualmente. El código legacy se ataca con testing y controlando la deuda técnica.

    El problema del programador que se va no se soluciona con documentación. Aunque la documentación estuviera actualizada tu puedes entender la documentación pero no el código. De nuevo aquí es muy útil el testing que da ejemplos de cómo se usa el código y también la propiedad colectiva del código, programación en parejas, etc.

    El problema de perder el control, o directamente no haberlo tenido nunca, tampoco se soluciona con documentación. Eso es sólo una ilusión. Mete personal técnico de la casa en el equipo de proyecto desde el principio y cuida la moral del equipo.

    Hay que asumir de una vez que el diseño es el código o el código es el diseño, como queramos verlo.
    Ahora, sí que es cierto que igual que se comenta el código para ayudar a entenderlo, en grandes o complejos sitemas siempre viene bien una guía de supervivencia básica fuera del código.

    • Milton Rafael Beltrant dice:

      Hola Julio:

      Gracias por tu comentario, que en parte se sale bastante de lo planteado de documentar en forma agil y genera sabor a la conversacion.

      Me gusta lo que expones al Final de “viene bien una guía básica de supervivencia”

      Esto es precisamente la documentacion ágil, la guía básica para cubrir la eventualidad cuando se retira un integrante o todo el equipo. Esta guía va ha ser mas o menos densa dependiendo de cada proyecto, y tambien del nivel de técnicos que se tengan a mano.

      Saludos.

  5. Catalina dice:

    Hola

    ¿Alguien tiene algún ejemplo de documentación ultra sencilla? Me imagino que algo básico podría ser un diagrama de componentes…

  6. Esta muy bueno el articulo, si hablamos de documentación agil entonces diria que los documentos que deberian elaborarse, una breve
    acta de constitucion del proyecto, con requerimientos generales sin detallar.
    El diagrama de despliegue(Explicado)
    El diagrama de componentes o Arquitectura de Software
    Patron de desarrollo a Usar (MVP o MVC)
    Informe de Tablas de Base de Datos.
    Flujos entre interfaces
    y lo más importante que te dira como creaste el software es
    Documentar las relaciones de base de datos.

  7. Laura dice:

    Interesante el post!…estoy con éste tema en un proyecto que llevamos en la oficina, no sabemos hasta que punto documentar ya que estamos acostumbrados al método tradicional y despegarse del mismo es muy complicado. Sería muy útil que en el post Javier Garzas referencie a los tipos de documentación sugeridas para el método scrum o en todo caso un libro que hable de ello.
    Saludos y gracias!

  8. Miguel Angel Jimenez dice:

    En efecto, es muy necesario tener una documentación sencilla y facíl de leer pero, en mi opinión la mejor forma de mantener un sistema documentado es, tener un documento de estándares para las aplicaciones venideras (Hablando de aplicaciones hechas en una misma herramienta), con el cual se siga una forma de desarrollo tan homogénea como sea posible, esto te garantiza que cualquier desarrollador o programador entienda lo que ya esta hecho y lo que el tiene que hacer.

  9. En documentación no está resuelta la cuestión, no hay recetas magicas que solucionan cualquier caso, hay que aplicar criterio e ir adaptando la misma en la medida que evolucione el sistema, para ello hay que asumir algo que no siempre se toma en cuenta:

    RECURSOS

    Los recursos dedicados a documentación con perfil funcional son fundamentales para llevar a cabo una que sirva (no tiene sentido que no tenga asignado el tiempo correspondiente para realizar esta tarea, he visto cuando lo hablan como “algo adicional” o “lo vamos haciendo en los tiempos libres”), y recursos que controlen la medida en la que se documenta en función de la visión global del proyecto.

    El código NO SIEMPRE dice lo que el desarrollador quería hacer.

  10. Anónimo dice:

    Y como sería la documentación ágil y se mantendría sincronizada con los cambios? solo diagramas?

Trackbacks/Pingbacks

  1. Soporte ágil: ¿Aplican las metodologías agiles a un departamento de soporte a incidencias? - Javier Garzás, sobre calidad software y otros temas relacionados - [...] Pero, desafortunadamente, muchos equipos  ágiles se caracterizan por no documentar (te recomiendo aquí este post sobre la documentación ágil).…
  2. La agilidad está muriendo. Bienvenido el postagilismo - Javier Garzás, sobre calidad software y otros temas relacionados - [...] leía ideas muy similares a las mías (y que muchas veces os he dejado por el blog, por ejemplo, por…

Dejar una respuesta

Tu dirección de correo electrónico no será publicada.

top