Documentacin de requisitos

La documentacin o especificacin de requisitos recoge el contrato

entre los desarrolladores y los stakeholders y sirve como herramienta
de comunicacin para los dos grupos. Su estilo y formalidad
dependern del proyecto, pero tambin del contexto en que se
desarrolla y de las personas participantes. Una de las tareas del
ingeniero de software ser, pues, evaluar cul es la necesidad de
formalidad y detalle a la hora de documentar los requisitos para un
proyecto. Hay que tener en cuenta que, desde el punto de vista del
xito o fracaso de un proyecto, es tan peligroso intentar desarrollar
el proyecto sin la suficiente documentacin de requisitos como
dedicar los recursos y el tiempo disponible a crear una documentacin
innecesariamente detallada o formal.

Caractersticas
requisitos

deseables

en

una

documentacin

de

Segn el estndar IEEE-830, una buena documentacin de requisitos

tendra que ser:
Correcta: Cada uno de los requisitos que constan es un requisito
que debe cumplir el sistema que hay que desarrollar.
Inambigua o no ambigua: Cada uno de los requisitos especificados
solo se puede interpretar de una manera.
Completa: Aparecen todos los requisitos del sistema que hay que
desarrollar, con independencia del tipo de requisito.
Consistente: No contiene ninguna contradiccin.
Ordenada: Est ordenada en funcin de la importancia y la
estabilidad de los requisitos.
Verificable: Cada uno de los requisitos que hay es verificable; es
decir, existe un proceso finito y con un costo razonable mediante el
cual una persona o entidad puede determinar si el sistema cumple o
no dicho requisito.
Modificable: Permite que se puedan realizar con facilidad cambios
en la documentacin (por ejemplo, que tenga tablas de contenidos,
referencias cruzadas, etc.)

 Trazable: El origen de cada requisito est claramente identificado

y, al mismo tiempo, se facilita la identificacin de cada requisito
para poder referenciarlo ms adelante durante el desarrollo del
sistema.

Tipos o estilos de documentacin de requisitos

Todo desarrollo de software que no sea trivial requiere que los
requisitos obtenidos y seleccionados estn documentados, no solo
para tenerlos registrados (y no tener que recordarlos), sino tambin
como herramienta de comunicacin entre las personas involucradas en
el proceso de desarrollo.
Las necesidades especficas de documentacin pueden variar mucho en
funcin del tipo de proyecto y de las metodologas de desarrollo
empleadas. Por lo que respecta a las necesidades de documentacin de
requisitos de un proyecto determinado, se puede distinguir dos ejes:

En el eje horizontal, se pueden clasificar las necesidades de

documentacin segn si esta tiene que ser exhaustiva (hay que
documentar todos los requisitos y todos los detalles de cada
requisito) o puede ser ms gil y permite documentar solo los
detalles ms relevantes de los requisitos ms importantes, de forma
que ser necesario mantener conversaciones con los stakeholders (que
no habr que documentar) para aclararlos. En el eje vertical, se
clasifican las necesidades de documentacin segn si es necesario
utilizar un lenguaje formal que garantice que la documentacin es no

ambigua, consistente y verificable, o se puede usar el lenguaje

natural de las personas que intervienen en el desarrollo.
En las siguientes lneas se explicar primero los dos grandes ejes
del grfico anterior, correspondientes a las siguientes necesidades
de documentacin de requisitos:
Documentacin exhaustiva - gil
Documentacin formal - no formal
A continuacin se propone un ejemplo de tcnicas y mtodos existentes
para cada una de las cuatro grandes reas del grfico,
correspondientes a las siguientes necesidades de documentacin de
requisitos:

Documentacin
Documentacin
Documentacin
Documentacin

exhaustiva y no formal (IEEE-830),

exhaustiva y formal (OCL),
gil y no formal (historias de usuario), y
gil y formal (especificacin por ejemplos).

Hay que tener en cuenta que la clasificacin propuesta no es de tipo

binario. Un proyecto puede requerir documentacin que tiende a ser
gil y que est a medio camino entre el lenguaje formal y el no
formal, por ejemplo. Teniendo esto en cuenta, los ejemplos que se
muestran a continuacin han sido elegidos por ser representativos de
los cuatro grandes cuadrantes.

Documentacin exhaustiva/gil
El estndar IEEE-830 recomienda que una especificacin tenga, entre
otras, la cualidad de estar completa. En este sentido, la
documentacin debera especificar todos los requisitos, tanto
funcionales como no funcionales, e incluir la definicin de las
respuestas a cualquier combinacin de entradas en todo tipo de
situaciones. Si se desea conseguir esta propiedad de la documentacin
de requisitos, se necesita que la documentacin sea totalmente
exhaustiva. Este tipo de documentacin permite, por ejemplo, que un
equipo que no ha participado en la documentacin de requisitos pueda
desarrollar el software a partir de ella. Pero la creacin de
documentacin exhaustiva requiere un gran esfuerzo.
El enfoque gil del desarrollo de software reconoce que, en muchos
casos, esta documentacin exhaustiva se acaba por no hacer o, peor
todava, acaba yendo en detrimento del software que funciona. Este
enfoque manifiesta que, a pesar de que la documentacin exhaustiva
tiene valor, el valor del software que funciona es an mayor y, por
este motivo, no se busca obtener una documentacin exhaustiva, sino
una documentacin suficiente (para crear el software que funcione).
As pues, se habla de documentacin gil de requisitos para referirse
a las situaciones en que la exhaustividad no es una cualidad
prioritaria de dicha documentacin. En estos entornos, un requisito
escrito en una tarjeta en papel puede ser suficiente si va acompaada
de las conversaciones necesarias para aclarar los detalles del
requisito; y dichas conversaciones no se documentan.

Documentacin en lenguaje formal/no formal

El estndar IEEE-830 tambin recomienda que una especificacin de
requisitos sea no ambigua, consistente y verificable. El espaol
como otros idiomas, as como cualquier otro lenguaje no formal, es
muy flexible pero, a la vez, requiere mucha atencin para asegurarse
de no caer en ambigedades y de que no se introduzcan
inconsistencias; adems, al ser totalmente abierto, puede dificultar
la verificacin de la documentacin.
Para evitar estas ambigedades, otra posibilidad consiste en usar un
lenguaje formal a la hora de describir los requisitos. Se trata, por
lo tanto, de usar un lenguaje definido formalmente y creado para no
admitir ambigedades y, a la vez, facilitar la verificacin y la
comprobacin de la consistencia de la documentacin de requisitos.

Documentacin exhaustiva y no formal: IEEE-830

Un ejemplo representativo de la documentacin exhaustiva pero en
lenguaje natural (y, por lo tanto, no formal) es el estndar IEEE830, publicado el 1998. Adems de indicar las propiedades deseables
de la documentacin de requisitos (entre las cuales incluye la
completitud), contiene indicaciones sobre cmo realizar una buena
especificacin de requisitos del software y propone una estructura
base para ella.
Segn el estndar IEEE-830, la especificacin de requisitos, que
deberan escribir clientes y proveedores en colaboracin, tiene que
responder a las siguientes preguntas:
Funcionalidad: Qu tiene que hacer el sistema que hay que
desarrollar?
Interfaces externas: Cmo interacta el software con las personas,
con el hardware o con otros sistemas software?
Rendimiento: Cul es la velocidad, disponibilidad, tiempo de
respuesta, tiempo de recuperacin, etc. que esperamos del software?
Atributos: Cules son las consideraciones respecto
portabilidad, correccin, mantenibilidad, seguridad, etc.?

Restricciones de diseo para la implementacin: Debe cumplir algn

estndar? Presenta alguna restriccin por lo que respecta al
lenguaje de programacin que hay que utilizar? Cules son las
polticas de gestin de datos (por ejemplo, relativas a la integridad
de los datos)? Existen limitaciones con respecto al entorno de
operacin? Etc.

Documentacin exhaustiva y formal: OCL

El lenguaje UML se puede utilizar como un lenguaje de modelado
formal, ya que permite, para determinados mbitos de la documentacin
de requisitos, como por ejemplo los requisitos de datos, expresar
formalmente los requisitos mediante modelos que se expresan en
diagramas que siguen cierta notacin grfica.
Sin embargo, hay cierta informacin que dicha notacin no puede
expresar, como algunas restricciones de integridad (por ejemplo,
decir que el tiempo mnimo de conexin entre dos vuelos es de una
hora) o las reglas de derivacin de la informacin derivada. En estos
casos, se necesita usar otro lenguaje (que podra ser el lenguaje
natural) para complementar los diagramas UML.
Por esta razn, la misma organizacin que publica el estndar UML
publica otro estndar llamado OCL (Object Constraint Language) Este
es un lenguaje declarativo formal para describir reglas que se
aplican a modelos UML y que fue creado, precisamente, para permitir
crear modelos formales ms completos.

Documentacin gil y no formal: Historias de usuario

La mayora de los proyectos de desarrollo gil utilizan una
documentacin no exhaustiva y no formal. El desarrollo gil se
caracteriza por priorizar la comunicacin verbal de los requisitos
por encima de su documentacin escrita con el fin de que la
comunicacin sea ms fluida y gil. En un entorno de desarrollo gil,
se suele usar la tcnica de las historias de usuario para organizar
los requisitos.
Una historia de usuario recoge qu es lo que necesita un usuario del
software (por ejemplo, qu cosas debe poder hacer) para alcanzar sus
objetivos. Los componentes bsicos de una historia de usuario son:
una descripcin corta (una frase) de la historia de usuario, que
sirve como recordatorio de que existe la historia y es til para
planificar.
una serie de conversaciones, que sirven para definir y aclarar los
detalles de la historia de usuario, y
un conjunto de criterios de aceptacin, que documentan los detalles
y que permiten determinar cundo est implementada completamente la
historia de usuario.

La principal ventaja de las historias de usuario y, al mismo tiempo,

su principal inconveniente, es que estn muy enfocadas a la
comunicacin verbal. Esto permite que la comunicacin sea ms gil
y fluida pero, en cambio, no deja constancia de todos los detalles
por escrito. Sin embargo, hay que tener en cuenta que la conclusin
final de las conversaciones s queda documentada en forma de pruebas
de aceptacin.

Documentacin gil y formal: Especificacin por ejemplos

A pesar de preferir la comunicacin verbal, el desarrollo gil
prioriza el software que funciona, y solo se puede comprobar que un
software funciona si los requisitos son verificables. De hecho, uno
de los doce principios del manifiesto gil es utilizar el software
que funciona como principal medida de progreso.
En este sentido, el uso de un lenguaje formal puede facilitar mucho
la verificacin de los requisitos para saber si el software funciona
como es debido o no.
Aun as, los lenguajes formales de especificacin plantean el
inconveniente de que, debido a su rigidez, dificultan la fluidez de
la comunicacin entre los clientes y los desarrolladores. Por eso,
los mtodos de desarrollo giles han creado lenguajes nuevos que
permiten equilibrar la necesidad de agilidad en la comunicacin y la
rigurosidad en la descripcin del problema.
Para encontrar este punto de equilibrio, estos mtodos se centran en
dos aspectos: por un lado, documentar lo mnimo imprescindible para
poder determinar, ms adelante, si el sistema cumple los requisitos
o no (los criterios de aceptacin) y, por otro lado, hacerlo en un
lenguaje que puedan interpretar al mismo tiempo tanto los
stakeholders como los programas de ejecucin automatizada de las
pruebas.
Por ejemplo, se puede documentar los criterios de aceptacin de la
siguiente manera:
Cuando sumamos 2 y 2, el resultado es 4.
Cuando sumamos 5 y 20, el resultado es 25.
Esta descripcin es muy fcil de entender para un stakeholder y, al
mismo tiempo, es muy fcil de interpretar por parte de un programa,
puesto que las dos frases tienen la misma estructura:
Cuando sumamos <num1> y <num2 > el resultado es <num1 + num2>

Una aproximacin formal a la documentacin de los criterios de

aceptacin consiste en escribir directamente pruebas de aceptacin
del sistema que se puedan ejecutar de forma automatizada. Dado que
tales pruebas se escriben en forma de ejemplos de utilizacin del
software, a menudo se usa el trmino especificacin por ejemplos
para hacer referencia a este estilo de especificacin.
Las pruebas de aceptacin verifican el comportamiento del sistema
en comparacin con los requisitos.
De hecho, al conocer las historias de usuario, se detecta que uno de
los tres elementos que forman las historias de usuario son los
criterios de aceptacin.
El uso de un lenguaje formal para definir los criterios de
aceptacin de una funcionalidad permite automatizar la ejecucin
de las pruebas de aceptacin.
Lo que interesa buscar en este lenguaje es que sirva, por un lado,
para que los clientes escriban sus criterios de aceptacin y, por
otro, para que un programa pueda interpretarlos y ejecutarlos a fin
de verificar si el sistema cumple dichos criterios o no.

Documentacin mediante casos de uso

Los casos de uso son una tcnica de documentacin de requisitos muy
extendida, entre otros motivos porque UML le da soporte. Se trata de
un enfoque en la manera de documentar requisitos que permite utilizar
varios grados de detalle y de formalismo, lo cual los hace adecuados
a escenarios muy diversos.
Un caso de uso recoge el contrato entre el sistema y los stakeholders
mediante la descripcin del comportamiento observable del sistema.
Un actor es una persona, una organizacin o un sistema informtico
que tiene capacidad de interactuar con el sistema y que presenta un
comportamiento propio. Cada caso de uso tiene un actor llamado actor
principal, que es quien utiliza el sistema para satisfacer un
objetivo. El caso de uso describe cul es el comportamiento
observable del sistema durante esta interaccin.
Sin embargo, en un mismo caso de uso, adems del actor principal,
pueden aparecer uno o ms actores de apoyo, tambin denominados
secundarios. Estos son actores externos al sistema que le
proporcionan un servicio.

Una de las ventajas de los casos de uso es que son muy flexibles por
lo que respecta al nivel de formalismo y la exhaustividad de su
descripcin. La misma tcnica permite hacer documentaciones desde
bastante giles hasta muy exhaustivas y desde nada formales hasta
bastante formales. Por eso en la asignatura se estudian de manera
separada del resto de los tipos o estilos de documentacin descritos
anteriormente.

Anatoma de un caso de uso

Existen varias formas, formatos y plantillas para describir un caso
de uso. Sin embargo, en la asignatura se considerarn los siguientes
elementos como fundamentales en la composicin de un caso de uso.
Nombre
Un caso de uso siempre debe tener un nombre. Este nombre es muy
importante, ya que se usar para hacer referencia al caso de uso
desde cualquier artefacto a lo largo del proyecto. Desde este punto
de vista, el nombre debe recoger la informacin ms importante
relativa al caso de uso (el objetivo que satisface). De este modo,
slo leyendo el nombre del caso de uso, los stakeholders pueden
valorar cul es el objetivo que satisface sin la necesidad de buscar
el documento en el que cual se describe.

Descripcin
Corresponde a un relato sencillo, pero no trivial, donde se explica
el propsito o finalidad del caso de uso.
Actores
Otro elemento muy importante es documentar claramente los actores
del caso de uso y cul de ellos es el actor principal.
Stakeholders
Cualquier persona o entidad que tenga inters o sufra algn impacto
por el cumplimiento del caso de uso.
Precondiciones
Las precondiciones del caso de uso indican qu condiciones se deben
dar para que se pueda llevar a cabo la interaccin descrita. A
diferencia de las condiciones de error (que s se deben en cuenta
como excepciones), los casos en los que no se cumplan estas
condiciones no se deben tener en cuenta y no formarn parte de la
descripcin del caso de uso.
Secuencia normal
La secuencia normal es una lista ordenada de acontecimientos que
espera el actor principal cuando pone en marcha la ejecucin del
caso de uso. La secuencia normal es un escenario de xito, donde el
actor principal satisface el objetivo por el que ha iniciado la
interaccin con el sistema. El resto de los escenarios (sean de
xito, fracaso o error) forman el conjunto de escenarios
alternativos, excepciones o extensiones.
Postcondiciones
Las postcondiciones refleja el estado en que se queda el sistema una
vez ejecutado el caso de uso, son los hechos que se han de cumplir
si el flujo de eventos normal se ha ejecutado correctamente. Las
garantas de xito o postcondiciones declaran que DEBE ser verdadero
cuando se completa exitosamente el caso de uso, sea a travs de su
escenario principal o a travs de un flujo alternativo

Excepciones
Un escenario de excepcin es una secuencia de pasos alternativos a
los del camino principal que lleva a que el objetivo del caso de uso
NO sea alcanzado, es decir que no se logre llegar a las
postcondiciones el sistema. Son caminos que hacen que el usuario no
pueda cumplir con su objetivo.