31. Redacción clara, precisa y verificable

Redactar requerimientos es una actividad técnica y comunicacional. Un buen requerimiento debe expresar una necesidad sin generar dudas, debe usar términos concretos y debe permitir comprobar objetivamente si fue cumplido.

La redacción no es un detalle menor. Una frase imprecisa puede convertirse en una funcionalidad mal construida, una prueba imposible de ejecutar o una discusión entre usuarios, analistas, desarrolladores y testers.

31.1 Introducción

En el tema anterior analizamos las características de un buen requerimiento. Ahora veremos cómo llevar esas características a la práctica mediante una redacción clara, precisa y verificable.

El objetivo no es escribir textos extensos ni complicados, sino expresar la necesidad correcta con el nivel de detalle adecuado para que pueda ser acordada, implementada y probada.

31.2 Qué significa redactar con claridad

Redactar con claridad significa que el requerimiento puede ser entendido sin explicaciones adicionales. La frase debe comunicar quién necesita algo, qué debe hacer el sistema, bajo qué condiciones y cuál es el resultado esperado.

La claridad se logra usando oraciones directas, evitando vueltas innecesarias y separando ideas diferentes en requerimientos diferentes.

31.3 Qué significa redactar con precisión

La precisión consiste en usar términos específicos y definidos. Un requerimiento preciso evita palabras vagas como "rápido", "simple", "adecuado", "intuitivo", "seguro" o "eficiente" cuando no están acompañadas por criterios concretos.

La precisión no implica escribir más, sino escribir mejor. Un dato exacto, una condición medible o una regla explícita pueden evitar muchas interpretaciones incorrectas.

31.4 Qué significa redactar de forma verificable

Un requerimiento verificable permite demostrar si el sistema lo cumple. Para eso debe existir una forma de probarlo, medirlo, inspeccionarlo o validarlo con evidencia observable.

Si el requerimiento no puede comprobarse, su aceptación dependerá de opiniones subjetivas. Por eso, la verificabilidad debe estar presente desde la redacción inicial.

31.5 Estructura básica de un requerimiento

Una estructura simple para redactar requerimientos funcionales es: actor, acción, objeto, condición y resultado esperado.

Por ejemplo: "El usuario administrador debe poder bloquear una cuenta de cliente cuando detecte actividad sospechosa, y el sistema debe impedir nuevos accesos desde esa cuenta hasta que sea reactivada".

31.6 Identificar el actor

El actor indica quién interactúa con el sistema o quién recibe el resultado. Puede ser una persona, un rol, otro sistema, un proceso automático o una entidad externa.

Es mejor escribir "el usuario de ventas", "el supervisor" o "el sistema de pagos" que usar expresiones genéricas como "se debe permitir" sin indicar a quién.

31.7 Describir una acción observable

La acción debe describir un comportamiento que pueda observarse. Verbos como registrar, consultar, modificar, eliminar, aprobar, rechazar, calcular, enviar o generar suelen ser más útiles que verbos vagos como gestionar, mejorar o facilitar.

Cuando se usa un verbo demasiado general, conviene preguntar qué acción concreta debe realizar el sistema.

31.8 Definir el objeto del requerimiento

El objeto indica sobre qué elemento actúa el requerimiento: una factura, un pedido, una cuenta, un informe, un usuario, una solicitud o cualquier otro elemento del dominio.

Definir correctamente el objeto evita confusiones y ayuda a relacionar el requerimiento con el modelo de datos, las reglas de negocio y las pruebas.

31.9 Indicar condiciones

Las condiciones aclaran cuándo aplica el requerimiento. Pueden estar relacionadas con estados, permisos, fechas, montos, perfiles, límites, configuraciones o reglas del negocio.

Por ejemplo, no es lo mismo decir "el usuario puede cancelar un pedido" que decir "el usuario puede cancelar un pedido mientras se encuentre en estado pendiente de preparación".

31.10 Expresar el resultado esperado

Todo requerimiento debe dejar claro qué debe ocurrir después de la acción. El resultado puede ser un cambio de estado, un mensaje, un registro creado, una notificación enviada, un cálculo realizado o una restricción aplicada.

Sin resultado esperado, el equipo puede implementar una acción incompleta o difícil de validar.

31.11 Palabras que conviene evitar

Algunas palabras generan ambigüedad si no se explican. Entre ellas se encuentran: rápido, eficiente, intuitivo, amigable, robusto, flexible, seguro, óptimo, adecuado, fácil, moderno y confiable.

No siempre deben eliminarse, pero sí deben acompañarse de criterios concretos. Por ejemplo, "rápido" puede convertirse en "la consulta debe responder en menos de tres segundos para el noventa y cinco por ciento de las solicitudes".

31.12 Convertir frases vagas en criterios concretos

Para mejorar una frase vaga, conviene preguntar cómo se comprobará su cumplimiento. Si alguien dice "el sistema debe ser seguro", se puede preguntar qué amenazas se quieren reducir, qué roles existen, qué datos son sensibles y qué controles son obligatorios.

Esta conversión permite transformar deseos generales en requerimientos verificables.

31.13 Redacción de requerimientos funcionales

Los requerimientos funcionales deben describir comportamientos del sistema. Es recomendable indicar el actor, la acción, los datos necesarios, las validaciones principales y el resultado.

Ejemplo: "El cajero debe poder registrar un pago en efectivo indicando importe, fecha y número de factura. El sistema debe marcar la factura como pagada cuando el importe recibido coincida con el saldo pendiente".

31.14 Redacción de requerimientos no funcionales

Los requerimientos no funcionales deben expresarse con métricas, condiciones y criterios de aceptación. No basta con decir que el sistema debe ser rápido, usable, disponible o seguro.

Ejemplo: "El sistema debe permitir iniciar sesión en menos de dos segundos para el noventa y cinco por ciento de los intentos realizados con hasta mil usuarios concurrentes".

31.15 Uso de criterios de aceptación

Los criterios de aceptación detallan las condiciones que deben cumplirse para considerar satisfecho un requerimiento. Ayudan a validar la interpretación y sirven como base para las pruebas.

Un criterio de aceptación debe ser observable. Por ejemplo: "Dado un usuario bloqueado, cuando intente iniciar sesión, entonces el sistema debe rechazar el acceso y mostrar un mensaje que indique que la cuenta está bloqueada".

31.16 Separar necesidad y solución

Una buena redacción debe evitar imponer una solución técnica sin explicar la necesidad. En algunos casos la solución es necesaria, pero debe estar justificada como restricción o decisión acordada.

Por ejemplo, "usar una base de datos específica" no describe por sí solo una necesidad del usuario. Puede ser una restricción técnica válida, pero debe documentarse como tal.

31.17 Mantener una sola idea por requerimiento

Cuando un requerimiento incluye varias ideas, se vuelve difícil saber si fue cumplido parcialmente, estimar su esfuerzo o escribir pruebas específicas.

Si una frase contiene muchas condiciones, varios actores o varias acciones principales, probablemente convenga dividirla en requerimientos más pequeños.

31.18 Usar términos del dominio

Los requerimientos deben usar el vocabulario propio del negocio. Si el dominio habla de pólizas, siniestros, afiliados, legajos o expedientes, esos términos deben usarse de manera consistente.

Cuando un término pueda tener más de un significado, debe definirse en un glosario para evitar interpretaciones distintas.

31.19 Ejemplo de mejora progresiva

Versión inicial: "El sistema debe permitir gestionar reclamos de manera eficiente".

Versión mejorada: "El operador de atención debe poder registrar un reclamo indicando cliente, motivo, descripción y prioridad. El sistema debe asignar un número único de reclamo y dejarlo en estado abierto".

Versión verificable: "El número único de reclamo debe generarse automáticamente y mostrarse al operador al finalizar el registro. El reclamo debe poder consultarse por número dentro de los cinco segundos posteriores a su creación".

31.20 Lista de revisión para la redacción

Antes de aprobar un requerimiento, conviene revisar:

• Si identifica claramente el actor o responsable.
• Si describe una acción concreta.
• Si indica el objeto sobre el que actúa.
• Si especifica condiciones relevantes.
• Si expresa un resultado esperado.
• Si puede probarse con criterios objetivos.
• Si evita palabras vagas o las convierte en métricas.
• Si contiene una sola necesidad principal.

31.21 Errores frecuentes

Los errores más comunes son escribir requerimientos demasiado generales, mezclar necesidades con soluciones, omitir excepciones, usar términos no definidos, no indicar prioridades y no incluir criterios de aceptación.

Otro error habitual es redactar solo desde el punto de vista técnico y olvidar que los interesados del negocio también deben poder leer y validar el contenido.

31.22 Buenas prácticas

Es recomendable redactar en voz activa, usar frases cortas, identificar actores y resultados, definir términos importantes, agregar ejemplos cuando haya reglas complejas y revisar cada requerimiento con usuarios y testers.

También conviene mantener plantillas simples, numerar los requerimientos, registrar cambios y relacionar cada requerimiento con sus criterios de aceptación.

31.23 Qué debes recordar

Un requerimiento claro se entiende, un requerimiento preciso evita interpretaciones y un requerimiento verificable permite comprobar si fue cumplido. Las tres cualidades deben aparecer juntas.

Redactar bien no significa escribir mucho. Significa escribir lo necesario para que todos compartan la misma interpretación.

31.24 Conclusión

La redacción de requerimientos transforma necesidades en acuerdos útiles para construir software. Cuando los requerimientos están escritos con claridad, precisión y verificabilidad, el equipo reduce incertidumbre y mejora la calidad de sus entregas.

En el siguiente tema veremos cómo utilizar plantillas y formatos de especificación para organizar los requerimientos de manera consistente dentro de un proyecto.