El proceso ágil: ¿cómo y qué debe documentarse?

Hace un tiempo, la compañía para la que trabajo había subcontratado un proyecto de desarrollo a un tercero. Emplearon prácticas ágiles en el desarrollo de la solución. Sin embargo, cuando se les pedía documentación, simplemente decían que era necesaria, ya que se incorporó en una wiki o como parte de sus sprints.

Se marcharon al finalizar el proyecto, con todos menos uno del equipo del proyecto. El sitio wiki del proyecto ahora se ha cerrado una vez que vence la suscripción anual.

Cuando se fueron, tomaron la mayor parte del conocimiento y la comprensión de lo que se desarrolló con ellos.

Entonces tengo 2 preguntas principales;

1. ¿Es esto normal para ágil o simplemente una excusa para no querer escribirlo?
2. ¿Cuáles son las normas de la industria para la documentación en proyectos ágiles para registrar requisitos de desarrollo, diseños, decisiones clave y contexto?

¿Es esto normal para ágil o simplemente una excusa para no querer escribirlo?

Mi teoría es que es por eso que el ágil se extendió tan rápido, especialmente el scrum . He visto demasiados equipos que desean ser ágiles para protegerse (en lugar de toda la empresa). El problema es que, en muchos casos, la gerencia usa la metodología contra ellos (¡porque ellos también quieren protegerse!).

¿Esto significa que ágil no funciona en absoluto? Por supuesto que no, esto solo significa que Agile te ayuda a resolver algunos problemas comunes, pero aún estás a cargo de todos los demás. Y en muchos casos ágil simplemente no es adecuado para ese equipo en esa empresa.

¿Cuáles son las normas de la industria para la documentación en proyectos ágiles para registrar requisitos de desarrollo, diseños, decisiones clave y contexto?

Para ser breve:

El equipo debe definir cuánta documentación necesitan

¡Conocen el dominio, son los expertos y, lo que es más importante, construyen la cosa!

Eso es lo que significa Software de trabajo sobre documentación integral en el Manifiesto Ágil .

¿Le dejaron un conjunto de pruebas TDD, pruebas de aceptación u otras pruebas unitarias? Ellos hacen un buen trabajo al documentar cómo funciona una aplicación y se espera que funcione, así como al proporcionar una implementación de muestra de cómo usar lo que se desarrolló.

Si bien no soy un experto ágil de ninguna manera, aquí está mi intento de respuesta:

1. ¿Hubo una historia / requisito que solicitaba documentación específica? Si no, entonces esto es parte del problema ya que obtienes lo que se solicita hasta cierto punto. Es una excusa y me pregunto qué quieres decir con "normal" aquí. ¿Es solo la mayoría de los que siguen los principios ágiles lo que hace que algo sea normal o es parte del proceso general que debería esperarse? Esas son las dos vistas que pude ver. EDITAR: Dudo que haya algo que la mayoría de los equipos hagan que sea igual cuando se trata de documentación, pero eso es una suposición de mi parte.

2. Un par de enlaces que pueden ser de interés es lo mejor que puedo hacer al respecto:

   • Mejores prácticas para la documentación ágil / esbelta
   • Documentación ágil y técnica

Agile tiene algunos puntos específicos en el manifiesto , donde señalaría este junto con la nota:

Software de trabajo sobre documentación completa

Es decir, si bien hay valor en los elementos de la derecha, valoramos más los elementos de la izquierda.

Son simplemente horribles. No creo que ágil signifique que no hay documentación en absoluto. Al menos deberían haber realizado un seguimiento de la descripción de la aplicación. Obtener una exportación de su wiki hubiera sido bueno o permitiría a otra persona cobrar la tarifa del servicio.

Puede que no sea tan detallado como algún intento. La teoría es que, en una crisis de tiempo, las especificaciones ya no coinciden con el código. Entonces, tiene suficiente documentación para escribir el código y no tratar de definirlo en detalle (algo así como escribir el código en algún código de texto / diagrama pseudo-verbalizado y luego en el código real).

Su problema no tiene nada que ver con Agile. Deberían haber producido la documentación que solicitó. El proyecto fue mal administrado.

Debe haber alguna descripción de las características, historias de usuarios y casos de prueba en algún lugar , como mínimo. Puede estar en archivos ReadMe en los proyectos, puede estar en los comentarios del código fuente, puede estar en documentos de diseño; podría ser todo lo anterior ... ¡o podría ser MIA!

En mi experiencia, siempre hay mucha gente que exige documentación (yo he sido uno de ellos), pero en la práctica nadie tiene tiempo o ganas de crearla. Ocasionalmente hay esfuerzos, pero la documentación creada generalmente se desactualiza muy rápido y se desincroniza con el funcionamiento real del sistema. Esto lleva a una situación en la que, incluso si tiene documentación, nadie se molesta en verificarla porque simplemente no confía en su precisión.

Para una precisión real e información confiable, todo se reduce a poder leer código y pruebas. Un cliente que quiera (re) descubrir lo que hace su sistema siempre puede entrevistar y consultar a un programador que luego puede presentar (con alguna investigación) hechos sobre el sistema.

Crear buena documentación no es trivial y puede ser bastante costoso. En segundo lugar, uno podría preguntarse acerca de la audiencia, ¿para quién es la documentación y qué se pretende proporcionar?