11. Documentación de requisitos y trazabilidad con decisiones posteriores

11.1 Introducción

Los requisitos describen necesidades, condiciones y restricciones que el sistema debe satisfacer. Documentarlos correctamente es una de las bases de un proyecto de software, porque muchas decisiones posteriores dependen de ellos: análisis, diseño, implementación, pruebas, despliegue y mantenimiento.

La documentación de requisitos no debe ser una colección de frases vagas. Debe permitir comprender qué se espera del sistema, por qué se necesita, quién lo solicita, bajo qué condiciones aplica y cómo se verificará.

Además, los requisitos deben poder relacionarse con decisiones posteriores. Esa relación se llama trazabilidad y permite responder preguntas como: qué diseño implementa este requisito, qué prueba lo verifica, qué API lo expone o qué decisión técnica se tomó para cumplirlo.

11.2 Qué es documentar requisitos

Documentar requisitos significa registrar de manera clara y organizada lo que el sistema debe hacer y las condiciones que debe cumplir. Puede incluir requisitos funcionales, requisitos no funcionales, reglas de negocio, restricciones técnicas, criterios de aceptación, prioridades y dependencias.

Un requisito bien documentado no solo expresa una necesidad. También reduce ambigüedad y permite que distintas personas trabajen con la misma interpretación. Desarrollo necesita entender qué construir. Pruebas necesita saber qué verificar. Gestión necesita comprender alcance. Soporte puede necesitar explicar comportamientos esperados.

11.3 Requisitos y trazabilidad

La imagen muestra la trazabilidad de requisitos: un requisito se conecta con reglas funcionales, decisiones de diseño, componentes de implementación, casos de prueba, documentación de usuario y mantenimiento. Esta conexión permite seguir el recorrido de una necesidad desde su origen hasta su verificación y evolución.

11.4 Requisitos funcionales

Los requisitos funcionales describen comportamientos o servicios que el sistema debe ofrecer. Indican qué acciones debe permitir, qué datos debe procesar, qué respuestas debe generar y qué reglas debe aplicar.

Por ejemplo: "El sistema debe permitir que un paciente reserve un turno con un profesional disponible". Esta frase comunica una funcionalidad, pero todavía puede requerir más detalle: qué datos se necesitan, cómo se determina disponibilidad, qué ocurre si otro paciente reserva al mismo tiempo y qué confirmación recibe el usuario.

Los requisitos funcionales suelen relacionarse con casos de uso, historias de usuario, escenarios, reglas de negocio, interfaces y pruebas funcionales.

11.5 Requisitos no funcionales

Los requisitos no funcionales describen cualidades o restricciones del sistema. Pueden referirse a rendimiento, seguridad, disponibilidad, usabilidad, accesibilidad, escalabilidad, mantenibilidad, compatibilidad, auditoría o cumplimiento normativo.

Estos requisitos deben escribirse con precisión. Decir "el sistema debe ser seguro" no alcanza. Es mejor indicar controles concretos: autenticación obligatoria, cifrado de datos sensibles, registro de accesos administrativos, bloqueo después de intentos fallidos o permisos por rol.

Los requisitos no funcionales suelen impactar decisiones de arquitectura, infraestructura, diseño, pruebas y operación. Por eso, su trazabilidad es especialmente importante.

11.6 Reglas de negocio

Las reglas de negocio son condiciones propias del dominio que el sistema debe respetar. Pueden indicar restricciones, cálculos, autorizaciones, plazos, estados, excepciones o comportamientos ante situaciones particulares.

Por ejemplo: "Un paciente puede cancelar un turno hasta 24 horas antes de la fecha y hora programadas". Esta regla debería conectarse con pantallas, servicios, validaciones, mensajes de error, pruebas y documentación de usuario.

Conviene documentar las reglas de negocio de forma explícita porque suelen ser fuente de errores cuando quedan escondidas en código, conversaciones o supuestos no escritos.

11.7 Criterios de aceptación

Los criterios de aceptación indican las condiciones que deben cumplirse para considerar que un requisito fue satisfecho. Ayudan a transformar una necesidad en algo verificable.

Por ejemplo, para reservar un turno, los criterios pueden indicar que el paciente debe estar autenticado, el profesional debe tener disponibilidad, el horario no debe estar ocupado, el sistema debe confirmar la reserva y debe enviarse una notificación.

Los criterios de aceptación son útiles para alinear producto, desarrollo y pruebas. También evitan que una funcionalidad parezca terminada aunque falten comportamientos importantes.

11.8 Identificadores de requisitos

Asignar identificadores a requisitos facilita la trazabilidad. Un identificador puede ser simple, como REQ-001, RF-012 o RNF-005. Lo importante es que sea estable y permita referenciar el requisito desde otros documentos.

Por ejemplo, un caso de prueba puede indicar que verifica RF-014. Una decisión de diseño puede indicar que se tomó para cumplir RNF-003. Un cambio solicitado puede mencionar qué requisitos afecta.

No todos los proyectos necesitan una numeración formal compleja, pero en sistemas medianos o grandes los identificadores ayudan mucho a mantener orden.

11.9 Trazabilidad hacia adelante y hacia atrás

La trazabilidad hacia adelante permite seguir un requisito hacia los elementos que lo implementan o verifican: diseño, código, pruebas, documentación de usuario y operación. Ayuda a saber qué se debe revisar cuando el requisito cambia.

La trazabilidad hacia atrás permite partir de una decisión, módulo o prueba y encontrar qué requisito la justifica. Esto ayuda a detectar elementos innecesarios, pruebas obsoletas o funcionalidades que no responden a una necesidad vigente.

11.10 Matriz de trazabilidad

Una matriz de trazabilidad es una tabla que relaciona requisitos con otros artefactos del proyecto. Puede vincular requisitos con casos de uso, reglas, componentes, endpoints, pruebas, decisiones o documentos.

No siempre se necesita una matriz formal, pero el concepto es útil. En proyectos pequeños puede bastar con enlaces entre documentos. En proyectos críticos, regulados o con muchos cambios, una matriz puede ser necesaria para demostrar cobertura y control.

11.11 Relación con casos de uso e historias de usuario

Los requisitos pueden documentarse mediante casos de uso, historias de usuario, escenarios o especificaciones más formales. Cada forma tiene ventajas. Los casos de uso ayudan a describir interacciones completas. Las historias de usuario son útiles para expresar valor desde la perspectiva del usuario. Los escenarios ayudan a precisar condiciones y resultados.

Lo importante es que la documentación elegida permita comprender y verificar el comportamiento. Una historia como "Como paciente quiero reservar un turno para recibir atención" necesita criterios de aceptación y reglas asociadas para ser implementable y verificable.

11.12 Relación con diseño e implementación

Las decisiones de diseño e implementación deberían poder explicarse a partir de requisitos. Si se crea un servicio, una tabla, una validación o un endpoint, conviene saber qué necesidad satisface.

Esto no significa que cada línea de código deba vincularse formalmente con un requisito. La trazabilidad debe aplicarse con criterio. Es más importante relacionar requisitos con decisiones, componentes, pruebas y contratos relevantes que intentar mapear cada detalle técnico.

Cuando un requisito cambia, la trazabilidad ayuda a identificar qué partes del diseño o implementación deben revisarse.

11.13 Relación con pruebas

Las pruebas son una de las principales formas de verificar requisitos. Por eso, cada requisito importante debería tener pruebas relacionadas. Si no existe ninguna prueba asociada, puede ser señal de que el requisito no está verificado o no fue escrito de manera comprobable.

La relación entre requisitos y pruebas permite medir cobertura funcional. También ayuda cuando se modifica una regla: el equipo puede saber qué pruebas revisar, actualizar o ejecutar.

En algunos contextos, las pruebas automatizadas pueden actuar como documentación ejecutable, pero aun así necesitan nombres claros y relación con comportamientos esperados.

11.14 Cambios en requisitos

Los requisitos cambian. Puede cambiar una regla del negocio, una prioridad, una restricción legal, una integración o una necesidad de usuario. La documentación debe permitir registrar esos cambios y evaluar su impacto.

Cuando un requisito cambia, conviene revisar documentos funcionales, diseño, pruebas, manuales, APIs y operación. La trazabilidad reduce el riesgo de actualizar una parte y olvidar otra.

También es útil conservar historial o registro de decisiones para entender por qué cambió un requisito y qué consecuencias tuvo.

11.15 Calidad de un requisito documentado

Un requisito documentado debe ser claro, necesario, verificable, consistente, trazable y posible dentro del contexto del proyecto. Si una de estas características falla, pueden aparecer problemas.

Un requisito no verificable dificulta las pruebas. Un requisito ambiguo genera interpretaciones distintas. Un requisito sin trazabilidad puede perderse durante el diseño o mantenimiento. Un requisito inconsistente puede contradecir otra regla.

Revisar la calidad de los requisitos antes de implementar reduce retrabajo.

11.16 Ejemplo aplicado: cancelación de turnos

Supongamos el requisito RF-002: "El sistema debe permitir que un paciente cancele un turno hasta 24 horas antes de la fecha y hora programadas". Este requisito puede relacionarse con la regla de negocio de cancelación, la pantalla de detalle del turno, el endpoint de cancelación, el servicio de reservas y los casos de prueba correspondientes.

También puede requerir mensajes de error: uno para turnos inexistentes, otro para turnos ya atendidos y otro para cancelaciones fuera de plazo. Si más adelante el plazo cambia de 24 a 12 horas, la trazabilidad permite identificar qué documentos, pruebas y componentes deben actualizarse.

11.17 Errores frecuentes

Al documentar requisitos y trazabilidad suelen aparecer estos errores:

• Escribir requisitos vagos que no pueden verificarse.
• Mezclar necesidades, soluciones técnicas y decisiones sin distinguirlas.
• No asignar identificadores ni referencias estables.
• Documentar reglas de negocio solo en conversaciones o código.
• No relacionar requisitos con pruebas.
• No revisar impactos cuando un requisito cambia.
• Crear matrices de trazabilidad demasiado pesadas que nadie mantiene.

11.18 Qué debes recordar de este tema

• La documentación de requisitos registra necesidades, reglas y restricciones del sistema.
• Los requisitos deben ser claros, verificables, consistentes y trazables.
• Los requisitos funcionales describen comportamientos; los no funcionales describen cualidades o restricciones.
• Las reglas de negocio deben documentarse explícitamente.
• Los criterios de aceptación ayudan a comprobar si un requisito fue satisfecho.
• La trazabilidad conecta requisitos con diseño, implementación, pruebas y documentación posterior.
• La trazabilidad debe ser útil y mantenible, no una carga innecesaria.

11.19 Conclusión

Documentar requisitos de manera clara permite construir una base sólida para el resto del proyecto. La trazabilidad agrega continuidad: conecta las necesidades iniciales con decisiones, diseño, código, pruebas y mantenimiento.

En el próximo tema estudiaremos la documentación funcional: procesos, reglas de negocio y comportamiento esperado.