Beneficios de la documentación ejecutable
Ivan Muchas de las documentaciones de los proyectos de software están desactualizadas. ¿No sería genial si su documentación reflejara realmente la funcionalidad del sistema? Una forma de hacerlo es crear documentación ejecutable, también conocida como especificaciones ejecutables.
Escribir documentación estática es útil, pero peligroso, ya que se vuelve vieja y obsoleta tan pronto como aparece la siguiente persona, debe actualizarse constantemente para que sea relevante en todo momento. Por ejemplo, con un enfoque de desarrollo dirigido por pruebas (TDD), parte del enfoque general de desarrollo dirigido por modelos ágiles, sus pruebas se convierten efectivamente en especificaciones detalladas. Te guste o no, la mayoría de los programadores no leen la documentación escrita de un sistema, en su lugar prefieren trabajar con el código. Cuando intentan entender una clase o una operación la mayoría de los programadores primero buscan código de ejemplo que ya lo invoque. Las pruebas unitarias bien escritas hacen exactamente esto – proporcionan una especificación de trabajo de su código funcional – y como resultado las pruebas unitarias se convierten efectivamente en una porción significativa de la documentación técnica.
Del mismo modo, las pruebas de aceptación pueden constituir una parte importante de la documentación de sus requisitos.
Las pruebas no son suficientes para la documentación, pero forman una parte importante de ella. Los requisitos y las pruebas son sólo dos caras de la misma moneda. No se puede tener una historia de usuario o un requisito sin un criterio de aceptación (prueba). Estos dos se funden en especificaciones ejecutables.
Estas especificaciones por ejemplo se convierten en documentos “verdes”. En lugar de tener largas hojas de cálculo de casos de prueba con los resultados esperados, los resultados reales y aprobar o rechazar, en su lugar representan los requisitos como especificaciones por ejemplo y los utilizan como pruebas automatizadas. Ayudan al equipo a pensar y a colaborar con el cliente, y comunican lo que la aplicación realmente hace. Si los requisitos cambian, el código fallará, por lo que será necesario corregir el código. De esta manera se le notifica y su “documentación” está siempre actualizada.
¿Por qué los arquitectos de software documentan sus proyectos de software?
1- Los interesados en el proyecto lo requieren
2- Comprender las compensaciones involucradas
3- Mantenimiento
4- Transferencia de conocimientos y memoria de organización
5- Pensar en algo
6- Control
La documentación es una parte importante de los proyectos de desarrollo de software ágil. Es fundamental comprender la necesidad de equilibrio, ya que algunas organizaciones valoran más ciertos documentos que otros. Pero casi todas deberían dar más prioridad a la creación de una documentación de arquitectura de software. En Apiumhub tenemos una perspectiva ágil en la documentación de software ya que consideramos que es una estrategia para contener los riesgos del proyecto y, por lo tanto, nos esforzamos por ser lo más eficientes posible.
Echemos un vistazo a las mejores prácticas de Modelado Ágil para aumentar la agilidad de la documentación:
- Escribir la documentación
– Preferir las especificaciones ejecutables a los documentos estáticos
– Documentar conceptos estables, no ideas especulativas
– Generar la documentación del sistema
- Simplificar la documentación
– Mantenga la documentación lo suficientemente simple, pero no demasiado simple
– Escribir el menor número de documentos con la menor superposición
– Poner la información en el lugar más apropiado
– Mostrar información públicamente
- Determinar qué se debe documentar
– Documento con un propósito
– Centrarse en las necesidades de los clientes reales del documento
– El cliente determina la suficiencia
- Determinar cuándo documentar
– Iterar y repetir
– Encontrar mejores formas de comunicarse
– Empieza con los modelos que realmente te mantienes al día…
– Actualizar sólo cuando duele
- Requiere documentación
– Tratar la documentación como un requisito
– Exigir a las personas que justifiquen las solicitudes de documentación
– Reconoce que necesitas documentación de software
Recuerda que un documento de arquitectura de software es un mapa del software. Lo usamos para ver, de un vistazo, cómo está estructurado el software. Te ayuda a entender los módulos y componentes sin necesidad de indagar en el código. Considéralo como una herramienta para comunicarse con los desarrolladores sobre el software.
