12. Documentación funcional: procesos, reglas de negocio y comportamiento esperado
12.1 Introducción
La documentación funcional describe cómo debe comportarse el sistema desde el punto de vista de sus funcionalidades. Su objetivo es explicar procesos, reglas de negocio, escenarios, validaciones, estados, excepciones y resultados esperados con suficiente claridad para que el equipo pueda construir, probar y mantener el software.
Este tipo de documentación se ubica entre los requisitos y la solución técnica. Toma necesidades del negocio y las transforma en comportamiento observable. No se concentra en la arquitectura interna, pero sí debe ser lo bastante precisa para orientar diseño, implementación y pruebas.
Una buena documentación funcional evita que cada persona interprete una funcionalidad de manera distinta. Permite que producto, análisis, desarrollo, pruebas y soporte compartan una misma descripción de lo que el sistema debe hacer.
12.2 Qué es la documentación funcional
La documentación funcional es la descripción organizada de las funciones que ofrece un sistema y de las reglas que gobiernan su comportamiento. Puede incluir flujos principales, flujos alternativos, datos de entrada, condiciones previas, resultados, mensajes, permisos, estados y excepciones.
A diferencia de una descripción comercial, la documentación funcional debe ser verificable. No alcanza con decir que el sistema "facilita la gestión de turnos". Debe explicar qué acciones se pueden realizar, quién puede realizarlas, con qué condiciones y qué ocurre en cada caso.
12.3 Elementos de la documentación funcional
La imagen muestra los elementos principales de la documentación funcional: procesos, actores, reglas de negocio, escenarios, estados, validaciones, excepciones, mensajes y resultados esperados. Todos estos elementos ayudan a describir el comportamiento del sistema de forma completa y comprensible.
12.4 Procesos funcionales
Un proceso funcional describe una secuencia de actividades orientada a un resultado del negocio. Puede involucrar usuarios, sistemas externos, reglas, decisiones y cambios de estado. Documentar procesos permite entender cómo una necesidad se transforma en acciones concretas dentro del sistema.
Por ejemplo, el proceso de reserva de un turno puede incluir búsqueda de profesional, selección de fecha, validación de disponibilidad, confirmación, creación de la reserva y notificación al paciente. Cada paso puede tener variantes y errores posibles.
Los procesos pueden representarse con texto, listas de pasos, tablas, diagramas de actividades o combinaciones de estos formatos. Lo importante es que el lector pueda seguir el flujo sin perder condiciones importantes.
12.5 Actores y roles
La documentación funcional debe indicar quién participa en cada funcionalidad. Un actor puede ser una persona, un rol, un sistema externo o un proceso automático. No todos los actores tienen los mismos permisos ni los mismos objetivos.
En un sistema de turnos, un paciente puede solicitar o cancelar turnos; un administrador puede modificar agendas; un profesional puede consultar su agenda; un sistema externo puede recibir notificaciones. Si estos roles no se distinguen, las reglas funcionales pueden quedar incompletas.
Documentar actores ayuda a definir permisos, validaciones, mensajes y escenarios de prueba.
12.6 Condiciones previas
Las condiciones previas indican qué debe cumplirse antes de ejecutar una funcionalidad. Pueden referirse a sesión iniciada, permisos, datos existentes, configuración, estado de una entidad o disponibilidad de un servicio externo.
Por ejemplo, para cancelar un turno puede ser necesario que el usuario esté autenticado, que el turno exista, que pertenezca al paciente o que el usuario tenga rol de administrador. Estas condiciones deben documentarse para evitar suposiciones.
Las condiciones previas ayudan a desarrollo y pruebas porque definen cuándo una funcionalidad puede comenzar correctamente.
12.7 Flujo principal
El flujo principal describe el camino esperado cuando todo ocurre correctamente. Es la secuencia básica de acciones y respuestas que permite alcanzar el resultado de la funcionalidad.
Un flujo principal debe ser claro y ordenado. Cada paso debería indicar quién actúa y qué hace el sistema. En lugar de escribir una explicación larga, suele ser más útil enumerar pasos breves.
Por ejemplo, para reservar un turno: el paciente busca un profesional, el sistema muestra disponibilidad, el paciente selecciona horario, el sistema valida que siga disponible, el paciente confirma y el sistema registra la reserva.
12.8 Flujos alternativos y excepciones
Los flujos alternativos describen variantes válidas del proceso. Las excepciones describen situaciones que impiden completar la operación o requieren un tratamiento especial. Ambos son importantes porque el software real rara vez sigue solo el camino ideal.
En la reserva de turnos, puede ocurrir que no haya disponibilidad, que el horario sea ocupado por otro paciente antes de confirmar, que el usuario no tenga permisos o que falle el envío de una notificación. Cada caso debe tener comportamiento esperado.
Documentar excepciones evita que el equipo decida respuestas improvisadas durante la implementación.
12.9 Reglas de negocio
Las reglas de negocio son condiciones propias del dominio que el sistema debe respetar. Pueden definir plazos, límites, permisos, cálculos, estados, restricciones o prioridades.
Una regla funcional debe ser precisa. Por ejemplo: "Un paciente puede cancelar un turno hasta 24 horas antes de la fecha y hora programadas". Esta regla es más útil que "el paciente puede cancelar con anticipación" porque permite validar el comportamiento.
Cuando hay muchas reglas, conviene numerarlas o identificarlas para poder referenciarlas desde escenarios, pruebas y mensajes.
12.10 Estados y transiciones
Muchas funcionalidades dependen del estado de una entidad. Un turno puede estar disponible, reservado, cancelado, atendido o ausente. Una solicitud puede estar pendiente, aprobada o rechazada. Un pago puede estar iniciado, confirmado o fallido.
Documentar estados ayuda a definir qué acciones son permitidas en cada momento. También evita transiciones inválidas, como cancelar un turno ya atendido o aprobar una solicitud rechazada sin reapertura.
Una tabla de estados puede ser más clara que una explicación larga cuando existen muchas combinaciones.
12.11 Validaciones
Las validaciones aseguran que los datos y condiciones sean correctos antes de completar una operación. Pueden aplicarse en formularios, servicios, reglas de negocio, APIs o procesos automáticos.
La documentación funcional debe indicar qué se valida, cuándo se valida, qué mensaje se muestra y si la operación se bloquea o continúa. Por ejemplo, puede validar que una fecha no esté en el pasado, que un campo obligatorio esté completo o que un horario siga disponible.
Las validaciones deben ser consistentes. Si una regla se valida en la interfaz pero no en el servicio, pueden aparecer errores o comportamientos inseguros.
12.12 Mensajes al usuario
Los mensajes forman parte del comportamiento funcional. Informan resultados, errores, advertencias o acciones necesarias. Un mensaje claro puede evitar consultas de soporte y mejorar la experiencia de uso.
La documentación funcional puede incluir mensajes exactos o criterios para redactarlos. En funcionalidades críticas, conviene indicar mensajes específicos para errores frecuentes: turno no disponible, sesión vencida, permiso insuficiente o cancelación fuera de plazo.
Los mensajes deben estar alineados con reglas y validaciones. Si una operación falla, el usuario debería comprender qué ocurrió y, si corresponde, qué puede hacer.
12.13 Datos de entrada y salida
Una funcionalidad suele recibir datos y producir resultados. Documentar entradas y salidas permite definir formularios, APIs, validaciones, pruebas y persistencia.
Para una reserva de turno, las entradas pueden ser paciente, profesional, especialidad, fecha y horario. Las salidas pueden incluir número de reserva, estado, confirmación y notificación. También puede haber errores con códigos o mensajes.
Cuando los datos son complejos, conviene usar tablas para indicar nombre, descripción, obligatoriedad, formato, ejemplo y reglas asociadas.
12.14 Tabla funcional de ejemplo
| Elemento | Descripción | Ejemplo |
|---|---|---|
| Actor principal | Rol que inicia la funcionalidad. | Paciente. |
| Condición previa | Situación necesaria antes de comenzar. | El paciente está autenticado. |
| Flujo principal | Secuencia normal de acciones. | Buscar, seleccionar, confirmar y registrar turno. |
| Regla de negocio | Restricción que debe respetarse. | No reservar horarios ocupados. |
| Resultado esperado | Estado final si todo fue correcto. | Turno reservado y confirmación enviada. |
12.15 Relación con pruebas
La documentación funcional debe facilitar la creación de pruebas. Cada flujo, regla, validación y excepción puede transformarse en uno o más casos de prueba. Si la documentación es ambigua, las pruebas también lo serán.
Por ejemplo, la regla de cancelación hasta 24 horas antes permite definir pruebas para cancelación válida, cancelación fuera de plazo, turno inexistente, turno ya atendido y usuario sin permisos. Cada prueba verifica una parte del comportamiento esperado.
Una buena documentación funcional permite detectar qué escenarios faltan antes de que el software llegue a producción.
12.16 Relación con diseño y APIs
Aunque la documentación funcional no describe la solución técnica en detalle, influye en ella. Las reglas funcionales pueden requerir servicios, endpoints, validaciones, estados, eventos o datos persistentes.
Por ejemplo, si la funcionalidad exige evitar reservas simultáneas del mismo horario, el diseño debe contemplar control de concurrencia. Si la documentación funcional indica notificaciones, la arquitectura debe considerar el mecanismo correspondiente.
Por eso, la documentación funcional debe estar disponible antes o durante el diseño, no después de implementar.
12.17 Errores frecuentes
Al escribir documentación funcional suelen aparecer estos errores:
- Describir solo el flujo exitoso y omitir alternativas y errores.
- Usar frases generales que no permiten diseñar pruebas.
- Mezclar comportamiento funcional con detalles internos de implementación.
- No indicar actores, permisos o condiciones previas.
- Omitir estados y transiciones importantes.
- No documentar mensajes de error o resultados esperados.
- No actualizar la documentación cuando cambia una regla de negocio.
12.18 Qué debes recordar de este tema
- La documentación funcional describe comportamiento esperado del sistema.
- Debe incluir procesos, actores, condiciones, flujos, reglas, validaciones y excepciones.
- Las reglas de negocio deben escribirse de forma precisa y verificable.
- Los estados y transiciones ayudan a definir acciones permitidas.
- Los mensajes y resultados esperados también forman parte del comportamiento funcional.
- La documentación funcional guía diseño, implementación y pruebas.
- Debe mantenerse actualizada cuando cambian reglas o procesos del negocio.
12.19 Conclusión
La documentación funcional convierte necesidades y reglas del negocio en comportamiento claro y verificable. Es una pieza fundamental para alinear producto, análisis, desarrollo, pruebas y soporte.
En el próximo tema estudiaremos la documentación de casos de uso, historias de usuario y escenarios, que son formas habituales de describir funcionalidades desde distintas perspectivas.