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.