13. Documentación de casos de uso, historias de usuario y escenarios
13.1 Introducción
Los casos de uso, las historias de usuario y los escenarios son formas de documentar funcionalidades desde la perspectiva de interacción entre personas, sistemas y objetivos. No reemplazan a toda la documentación funcional, pero ayudan a describir qué quiere lograr un actor, qué pasos ocurren y qué resultados se esperan.
Cada técnica tiene un énfasis distinto. Los casos de uso describen interacciones completas entre actores y sistema. Las historias de usuario expresan valor desde la perspectiva de un rol. Los escenarios muestran situaciones concretas, con condiciones, acciones y resultados específicos.
En documentación técnica, estas formas permiten conectar requisitos, comportamiento funcional, pruebas y comunicación con usuarios o responsables del producto.
13.2 Por qué documentar interacciones
Muchas funcionalidades no se entienden bien si solo se nombran. Decir "gestionar turnos" es demasiado amplio. Documentar la interacción permite explicar quién inicia la acción, qué información necesita, qué valida el sistema, qué alternativas existen y cómo termina el proceso.
Las interacciones también revelan excepciones. Un usuario puede no tener permisos, puede faltar disponibilidad, puede fallar una integración o puede existir un dato inconsistente. Si esos casos no se documentan, probablemente aparezcan tarde durante desarrollo, pruebas o soporte.
13.3 Tres formas complementarias
La imagen muestra casos de uso, historias de usuario y escenarios como tres formas complementarias de documentar comportamiento funcional. Los casos de uso organizan interacciones, las historias de usuario expresan valor y los escenarios concretan situaciones para análisis y pruebas.
13.4 Casos de uso
Un caso de uso describe una interacción entre un actor y el sistema para alcanzar un objetivo. Suele incluir nombre, actor principal, objetivo, condiciones previas, flujo principal, flujos alternativos, excepciones y resultado final.
Los casos de uso son útiles cuando la funcionalidad tiene varios pasos, reglas o variantes. Permiten describir una operación completa sin entrar en detalles internos de implementación.
Por ejemplo, "Reservar turno" puede ser un caso de uso que involucra al paciente, al sistema de turnos y posiblemente a un servicio de notificaciones.
13.5 Elementos de un caso de uso
Un caso de uso completo puede incluir varios elementos. No todos son obligatorios en todos los proyectos, pero conviene conocerlos:
- Nombre: expresa la acción principal, por ejemplo "Reservar turno".
- Actor principal: rol que inicia la interacción.
- Objetivo: resultado que el actor quiere lograr.
- Condiciones previas: situaciones necesarias antes de comenzar.
- Flujo principal: pasos esperados cuando todo ocurre correctamente.
- Flujos alternativos: variantes válidas del proceso.
- Excepciones: situaciones de error o imposibilidad.
- Resultado final: estado esperado al terminar.
13.6 Ejemplo de caso de uso
| Nombre | Reservar turno |
|---|---|
| Actor principal | Paciente |
| Objetivo | Obtener un turno con un profesional disponible. |
| Condiciones previas | El paciente está autenticado y existen profesionales con agenda publicada. |
| Flujo principal | Buscar profesional, seleccionar fecha, elegir horario, confirmar reserva y recibir confirmación. |
| Resultado final | El turno queda reservado y asociado al paciente. |
13.7 Flujos alternativos y excepciones
Un caso de uso no debe limitarse al flujo ideal. Los flujos alternativos y excepciones son necesarios para describir qué ocurre cuando el proceso se desvía del camino principal.
En "Reservar turno", un flujo alternativo puede permitir cambiar la fecha antes de confirmar. Una excepción puede ocurrir si el horario fue reservado por otra persona, si el paciente perdió la sesión o si el profesional ya no está disponible.
Documentar estos casos evita decisiones improvisadas en desarrollo y facilita la creación de pruebas.
13.8 Historias de usuario
Una historia de usuario expresa una necesidad desde el punto de vista de un rol. Un formato habitual es: "Como [rol], quiero [objetivo], para [beneficio]". Este formato ayuda a conectar funcionalidad con valor.
Por ejemplo: "Como paciente, quiero reservar un turno en línea, para no tener que comunicarme telefónicamente con la clínica". La historia identifica quién necesita la funcionalidad, qué quiere lograr y por qué importa.
Las historias de usuario son útiles para planificar trabajo incremental, conversar con responsables del producto y definir criterios de aceptación.
13.9 Criterios de aceptación en historias
Una historia de usuario necesita criterios de aceptación para volverse verificable. Sin criterios, puede quedar demasiado abierta. Los criterios indican condiciones que deben cumplirse para considerar que la historia está terminada.
Para la historia de reservar turno, algunos criterios pueden ser: el paciente puede ver horarios disponibles, no puede reservar horarios ocupados, recibe confirmación al finalizar y el turno aparece en su listado.
Los criterios de aceptación ayudan a alinear producto, desarrollo y pruebas.
13.10 Escenarios
Un escenario describe una situación concreta. Puede representar un caso exitoso, una alternativa o un error. Los escenarios son útiles porque muestran cómo se comporta el sistema con datos y condiciones específicas.
Por ejemplo: "Paciente autenticado reserva un turno disponible para el martes a las 10:00". Otro escenario puede ser: "Paciente intenta reservar un horario que acaba de ser ocupado".
Los escenarios facilitan la conversación y pueden convertirse directamente en casos de prueba.
13.11 Escenarios con formato dado-cuando-entonces
Un formato común para escenarios es dado-cuando-entonces. "Dado" describe el contexto inicial. "Cuando" describe la acción. "Entonces" describe el resultado esperado.
Este formato obliga a separar contexto, acción y resultado. Por eso es útil para pruebas, criterios de aceptación y reglas funcionales.
13.12 Comparación entre técnicas
| Técnica | Enfoque | Cuándo conviene usarla |
|---|---|---|
| Caso de uso | Interacción completa entre actor y sistema. | Procesos con varios pasos, alternativas y excepciones. |
| Historia de usuario | Necesidad y valor desde un rol. | Planificación incremental y conversación con producto. |
| Escenario | Situación concreta con condiciones y resultado. | Criterios de aceptación, pruebas y ejemplos específicos. |
13.13 Relación con documentación funcional
Casos de uso, historias y escenarios pueden formar parte de la documentación funcional. Ayudan a describir comportamiento desde perspectivas complementarias. Una historia puede expresar valor, un caso de uso puede desarrollar el flujo y varios escenarios pueden precisar condiciones de aceptación.
Lo importante es evitar duplicación contradictoria. Si una regla cambia, debe actualizarse en todos los lugares donde se documenta o, mejor, centralizar la regla y referenciarla desde historias y casos de uso.
13.14 Relación con pruebas
Los escenarios y criterios de aceptación son una base natural para pruebas. Cada condición importante puede convertirse en un caso de prueba. Esto permite verificar que la funcionalidad implementada coincide con lo documentado.
Por ejemplo, una historia de cancelación de turno puede generar pruebas para cancelación válida, cancelación fuera de plazo, turno inexistente, usuario sin permisos y turno ya atendido.
Cuando las pruebas se vinculan con escenarios documentados, la trazabilidad mejora y es más fácil revisar impactos ante cambios.
13.15 Nivel de detalle adecuado
El nivel de detalle debe ajustarse al riesgo y complejidad de la funcionalidad. Una acción simple puede documentarse con una historia y criterios breves. Un proceso crítico puede necesitar caso de uso completo, reglas, escenarios y pruebas detalladas.
Documentar demasiado una funcionalidad simple puede generar carga innecesaria. Documentar poco una funcionalidad compleja puede causar errores. El criterio debe ser la utilidad para comprender, construir y verificar.
13.16 Errores frecuentes
Al documentar casos de uso, historias y escenarios suelen aparecer estos errores:
- Escribir historias de usuario sin criterios de aceptación.
- Describir solo el flujo principal y omitir excepciones.
- Confundir objetivo del usuario con detalle técnico de implementación.
- Usar actores demasiado genéricos, como "usuario", cuando hay roles diferentes.
- Duplicar reglas en varios documentos y actualizarlas de forma inconsistente.
- Crear escenarios sin resultado esperado verificable.
- Documentar casos de uso tan extensos que nadie los consulta.
13.17 Qué debes recordar de este tema
- Los casos de uso describen interacciones completas entre actores y sistema.
- Las historias de usuario expresan necesidad y valor desde un rol.
- Los escenarios describen situaciones concretas con condiciones y resultados.
- Los criterios de aceptación vuelven verificables las historias.
- Los flujos alternativos y excepciones son parte esencial del comportamiento.
- Estas técnicas complementan la documentación funcional.
- El nivel de detalle debe depender de la complejidad y riesgo de la funcionalidad.
13.18 Conclusión
Casos de uso, historias de usuario y escenarios ayudan a documentar funcionalidades de manera comprensible y verificable. Permiten describir objetivos, interacciones, condiciones, alternativas y resultados esperados.
En el próximo tema veremos el uso de diagramas y modelos como apoyo de la documentación técnica.