Diseñar documentos como parte de Agile

En mi lugar de trabajo, nos enfrentamos a un desafío porque "ágil" con demasiada frecuencia ha significado "requisitos vagos, malos criterios de aceptación, ¡buena suerte!" Estamos tratando de abordar eso, como un esfuerzo de mejora general.

Entonces, como parte de eso, propongo que generemos documentos de diseño que, más allá del nivel de la historia del usuario, reflejen con precisión el resultado de investigaciones preliminares del efecto de una característica dada dentro del sistema e incluyan respuestas a las preguntas que tenemos preguntó el negocio.

¿Existe un estándar efectivo para esto?

Actualmente enfrentamos una situación en la que una nueva característica puede afectar múltiples áreas en nuestro sistema de "gran bola de lodo" , y las estimaciones están comenzando a aumentar debido a esta deuda técnica. Esperemos que procesos de diseño más reflexivos puedan ayudar.

"requisitos vagos, malos criterios de aceptación, ¡buena suerte!"

sí, ¡este es el mismo tipo de requisitos que usted tiene incluso si intenta fijarlos también! (como ejemplo, un documento de requisitos de 10.000 que tardó 4 años en crear un cliente del gobierno todavía estaba lleno de inconsistencias, vaguedades e incluso declaraciones internamente contradictorias. Si 4 años de documentación de requisitos no pueden darle un requisito decente, exacto, haga ¿Alguna vez pensaste que serías capaz de obtener algo no vago?)

Entonces ... se inventó la forma ágil para comprender que esto sucede y trabajar con él en lugar de tratar de trabajar en su contra.

Empiezas preguntando "qué quieres" y el cliente responde con "algo así". Haces un trabajo y luego vuelves al cliente y le dices "¿es esto lo que querías?", Y el cliente por lo general dice "sí, pero ...", y entonces le preguntas "qué quieres".

Eventualmente, obtienes exactamente lo que el cliente quería, ¡incluso si no saben qué es eso! (Diablos, nunca saben lo que quieren, no exactamente).

En nuestro equipo, desde que fuimos ágiles, también hemos estado tratando de reducir y comprender cuánta documentación se requiere realmente. Puedo compartir contigo lo que hemos aprendido hasta ahora.

Antes que nada, asegúrese de leer este artículo sobre la documentación ágil / esbelta . Muy buena lectura.

En segundo lugar, le recomiendo encarecidamente que reconsidere la producción de documentos de diseño después del trabajo preliminar sobre historias. Lo hemos intentado antes y ha demostrado ser un desperdicio. A mediados de la última versión, hemos decidido actualizar los documentos de diseño SOLO DESPUÉS de que se entregue el código de la historia. Y ahora estoy pensando que incluso eso es demasiado pronto.

Debe preguntarse por qué desea hacer documentos de diseño antes de la codificación. Para nosotros estas fueron las razones:

1. Nosotros como equipo necesitamos entender cómo la historia afectará el diseño.
2. Tener documentos de diseño ha demostrado ser útil cuando los miembros nuevos (o temporales) se unen al equipo o cuando regresan al código en el que nadie ha trabajado durante más de un año. Por lo tanto, son útiles para la memoria organizacional para ayudar a comprender cómo funciona el código.
3. Los documentos de diseño son útiles para los ingenieros de mantenimiento que pueden necesitar solucionar el código después del lanzamiento.

Para satisfacer (1) no necesita producir un documento de diseño real. Su equipo aún debe tener una fase de diseño antes de la codificación, pero esa fase puede ser tan simple como una sesión de 15 minutos frente a una pizarra o una servilleta. No necesita producir un documento real que tomará horas (si no días) para escribir solo para discutir los cambios de diseño.

(2) o (3) no son necesarios durante el desarrollo de la historia actual y es más que probable que no sean necesarios para varias iteraciones posteriores.

También tenga en cuenta que cada vez que un miembro del equipo escribe / actualiza documentos de diseño, ese es el momento en que no se escribe el código. Cuando escribes documentos antes del código real, hay casi un 100% de posibilidades de que necesiten actualizarse porque una vez que comienzas a codificar, el diseño siempre termina siendo modificado. E incluso si escribe documentos de diseño después del código, como nuestro equipo ha aprendido, la refactorización de historias posteriores todavía altera el diseño.

Entonces, lo que recomendaría:

1. Inicialmente produzca diseños / modelos temporales suficientes para que su equipo pueda tener una conversación inteligente antes de la codificación. No espere conservarlos y no pierda tiempo en formalizarlos.
2. Solo produzca documentación de diseño oficial si alguien la necesita (es decir, su equipo tiene una necesidad real de memoria organizacional)
3. Solo produzca documentación de diseño en código que se haya estabilizado. No tiene sentido tratar de documentar un módulo que se cambia constantemente en cada iteración.
4. Produzca documentos de diseño que describan completamente un módulo (o parte del producto). En el pasado solíamos escribir documentos de diseño que documentaban los cambios que debían hacerse. Esos documentos fueron completamente inútiles tan pronto como se realizó el lanzamiento.
5. Mantenga el documento de muy alto nivel. Si escribe 20 páginas sobre arquitectura y diseño de muy alto nivel, ese documento a) será leído por otras personas yb) ayudará a las personas a familiarizarse con el diseño general de su código. Para más detalles, las personas pueden ir directamente al código. Si escribe 700 páginas de especificación detallada, casi siempre no coincidirán con la realidad, es demasiado para que cualquiera lo lea y terminará teniendo que mantener y actualizar 700 páginas en lugar de 20 cada vez que se realicen cambios futuros.

El "mantra" ágil no tiene que ver sin documentación por completo.

El mantra ágil es preferir " software de trabajo a documentación completa ". Pero tenga en cuenta la parte inferior del manifiesto.

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

El tío Bob tiene una buena política de documentación.

No presente ningún documento a menos que su necesidad sea inmediata y significativa .

Tienes razón en que algunas personas usan Agile como una excusa para no producir documentación, pero eso es malo Agile. Está ignorando los bits que he resaltado en las citas anteriores.

Dicho todo esto, cuando dice 'actualmente enfrentamos una situación en la que una nueva característica puede afectar múltiples áreas en nuestro sistema de "gran bola de lodo", si va a ser ágil, debe hacer algo al respecto.

Cuando tenga su documentación, úsela para modularizar su código. De esa forma, elimina la necesidad a largo plazo de mantener la documentación (lo que no sucederá) eliminando la necesidad a largo plazo de la documentación.

es decir. Haga que la necesidad sea inmediata y significativa.

Lo que pasa con ágil es que los esfuerzos de documentación realmente deben ser impulsados ​​por el equipo scrum. Si los desarrolladores no creen que la documentación externa sea suficiente para sus necesidades, la historia del usuario se bloquea hasta que lo hagan. Si la empresa considera que los desarrolladores no están produciendo la documentación adecuada, el propietario del producto insiste en que forme parte de los criterios de aceptación. Debido a esto, he encontrado que nuestra documentación está más enfocada y efectiva desde que me mudé a scrum.

Usamos VersionOne para rastrear nuestras historias de usuarios, pero estoy seguro de que nuestros métodos se aplican a otros sistemas. Le permite adjuntar archivos a historias de usuarios. Hemos encontrado que es un lugar extremadamente útil para colocar documentos de diseño.

Para un ejemplo que funcionó realmente bien para nosotros, tuvimos que probar un nuevo diseño de placa de circuito lo más rápido posible después de que se construyó el prototipo. Hicimos dos historias de usuarios para todo lo que necesitaba pruebas: una para diseñar la prueba y otra para ejecutarla. Un criterio de aceptación para la historia de diseño fue que el procedimiento de prueba estaba completamente documentado en la historia de ejecución.

Cuando llegamos a la parte de prueba, todo salió mejor que nunca. Acabamos de abrir la historia del usuario y seguimos el procedimiento paso a paso. La documentación era exactamente lo que necesitábamos para completar la historia, ni más ni menos.

Tenemos otra historia en nuestra cartera de pedidos solo para mejorar la documentación de un chip que utilizamos, a fin de facilitar que otros equipos lo recojan para sus propios productos.

En resumen, si siente que su documentación está sufriendo, la solución es tan fácil como hacer una historia de usuario separada para ella y / o hacerla parte de los criterios de aceptación.

Cuando habla de requisitos deficientes, lo primero que me viene a la mente es asegurarme de que tenga los criterios de prueba. Si es posible, cree algunos casos de prueba automatizados reutilizables para partes existentes del sistema. Una vez que todos se sientan cómodos con eso, pase a escribir los casos de prueba antes de escribir el código. Los buenos casos de prueba pueden hacer mucho para documentar los comportamientos de un sistema.

En cuanto a qué documentos de diseño específicos usar, como ya han dicho otros, depende en gran medida de las necesidades del equipo y de cuál será la próxima tarea que emprenderán. Cuando sea posible, intente usar herramientas que puedan generar los documentos (del código) que usaría, o generar el código del documento. El mantenimiento de la documentación puede ser bastante costoso, así que elija sabiamente cuando conserve un documento de diseño.

Personalmente, he tenido mucho éxito con los diagramas de clases generados a partir de códigos y casos de prueba de fitnesse. El equipo imprime un par de diagramas de clase, realiza una sesión de marcado con el propietario del producto y luego formula una estimación a partir de ahí. En lo que respecta a fitnesse, tengo la suerte de trabajar con un par de propietarios de productos que son muy buenos para expresar lo que quieren en hojas de cálculo, que luego se convierten en tablas para fitnesse.