Creo que frustración es la palabra que más se aproxima a lo que la mayoría de las personas sienten cuando tratan con programadores. Frustración en el sentido de diferencia entre expectativas y realidad. Es este artículo sugiero una plantilla con una serie de puntos que pedirle a un programador que se supone que va a entregar algo, para evitar malentendidos. Hay cosas que hay que pedirle antes de que empiece el trabajo y otras después. No entraré en metodología de seguimiento de proyecto, sólo en la documentación que debe se debe exigir.
Antes de la entrega
1 Identificación de la tarea
Debería incluir cómo mínimo:
- tipo de tarea, si es una mejora, corregir un error o cambiar algo que ya existe
- número de referencia único para trazar cada tarea
- números de referencia de tareas relacionadas
- la versión del programa sobre la que se realizarán los cambios
2 Descripción de la funcionalidad
La descripción de la funcionaldiad deseada es teóricamente responsabilidad del analista funcional, o del cliente, pero nunca hay que dejar que una persona sin conocimientos técnicos diseñe en solitario una funcionalidad.
En la redacción de especificaciones existe una jerga de moda que es cómo en este ejemplo:
Cómo administrador de la trastienda u operador de la trastienda con permiso de modificar pedidos quiero que el formulario de edición de pedido me permita modificar la cantidad de items en una línea del pedido siempre y cuando el pedido no haya sido ya empaquetado para su envío de manera que el cliente pueda hacer cambios de último minuto llamando por teléfono si se ha equivocado en un pedido.
Nótese que la especificación del requerimiento contiene:
- el actor (administrador u operador con privilegios).
- lo que se pide (modificar la cantidad de ítems).
- los prerrequisitos (que el pedido no haya sido empaquetado).
- lo que se pretende conseguir con el cambio.
La descripción debe ser tan detallada cómo sea posible, incluyendo, si procede:
- diagramas de flujos de datos
- diagramas de transiciones de estado
- diagramas de procesos de negocio
- wireframes o mock ups de las pantallas
La descripción debe incluir también una explicación paso a paso de cómo reproducir el error, si es un error, o de cómo se espera que el usuario utilice la funcionalidad incluyendo requerimientos de accesibilidad.
3 Criterio de aceptación
Aquí se especifica qué comportamiento debe exhibir el software entregado para que sea aceptable como solución al problema planteado. La especificación debe explicar sin ambigüedades el comportamiento actual (AS-IS) versus el comportamiento esperado (TO-BE).
Siguiendo con el ejemplo anterior el criterio de aceptación podría ser:
1. Entrar en la trastienda y buscar un pedido.
2. Acceder al formulario de edición de pedido.
3. Si el pedido ya ha sido empaquetado para envío o ha sido cancelado entonces no es posible modificar la cantidad de ítems en cada línea.
4. Si el pedido no ha sido aún empaquetado para envío entonces aparecerá un botón [Editar Cantidades] que permitirá cambiar la cantidad de ítems en cada línea.
5. Cuando se cambia la cantidad el precio varía de forma acorde.
6. No es posible especificar cantidades por encima del stock disponible.
7. Si una cantidad se pone a cero entonces la línea de pedido desaparecerá cuando se grabe el pedido.
Es posible y deseable añadir también requerimientos no funcionales. Típicamente estos son el tiempo máximo que una transacción puede durar y cuántas transacciones concurrentes debe ser capaz de atender el sistema sin sobrepasar el tiempo máximo de servicio.
4 Finalidad y principios
Aquí se explica el propósito último del cambio. Por ejemplo, si se trata de mejorar la experiencia del cliente priorizando la consistencia del interfaz sobre su simplicidad. O si es un cambio puramente técnico cual es el compromiso entre velocidad y uso de memoria.
5 Cambios en el modelo de datos
De manera que se pueda saber fácilmente qué nueva información estará disponible para explotación o qué otros sistemas habría que modificar al ser afectados por un cambio en el modelo de datos.
6 Consideraciones de diseño técnico
- Listado de asunciones y dependencias.
- Referencias a documentación y notas de reuniones.
- Descripción de las restricciones: throughput, latencia, ancho de banda, integridad de datos, seguridad…
- Si se está desarrollando un API o servicio, documentación estructurada tipo JavaDoc o Swagger.
7 Notas de implementación
En ellas se enumeran las partes del software que serán creadas o modificadas con una descripción de los cambios a realizar en cada parte. Las notas de implementación deben explicar cómo los cambios técnicos casan con el criterio de aceptación.
8 Interfaces
Listado de los sistemas con los que se comunica el software a modificar y cómo se interactúa con dichos sistemas.
9 Plan de pruebas
Las pruebas son resumidamente de cuatro tipos:
- Pruebas unitarias
- Pruebas de integración
- Pruebas de rendimiento
- Pruebas de seguridad
10 Plan de despliegue
Dónde se instalará el nuevo sóftware, en que máquinas y entornos.
Si la funcionalidad requiere cambios en la configuración, cómo instalar un certificado digital, abrir un puerto en el firewall, instalar una librería, etc.13 Documentación
Cómo mínimo el manual de usuario y la guía de operación.
11 Estimación de esfuerzo y plazos de entrega
Cuántas horas/hombre costará el desarrollo. Cómo se encajan dichas horas/hombre en un calendario.
Después de la entrega
11 Evidencias
Cuando esté desarrollado el software, videos o capturas de pantalla que muestren su funcionamiento.
12 Bitácora de trabajo
Donde figuran las horas empleadas en cada tarea con fines de contabilidad analítica y mejora de las estimaciones en futuros desarrollos.
13 Resultados de las pruebas
Explicando qué se ha probado, con cuántos usuarios y datos se hicieron las pruebas de carga y sobre qué hardware.
También cómo se hizo el análisis de vulnerabilidades de seguridad y se se encontró alguna.
Post relacionado: Cómo estimar el esfuerzo en desarrollo de software
