Sobre documentación y requerimientos

La primera vez que desarrolle software para un cliente de manera profesional (porque recibí dinero a cambio) fue para la construcción de un pequeño sistema administrativo junto a unos amigos. Como pasa generalmente en estos casos, el aprendizaje que obtuve de este proyecto paso más por cómo no se deben hacer las cosas que por cómo hacerlas bien.

Entre todos los problemas que nos encargamos cuidadosamente de tener a lo largo del proyecto, uno de los principales fue la falta de definición y gestión de requerimientos.

Al inicio tuvimos un par de charlas con el cliente aunque sin hablar con demasiado detalle y sin definir un alcance claro. Durante el proyecto tuvimos alguna reunión ocasional con el cliente para presentar el avance del desarrollo, aunque más que presentar el avance, en la reunión mostrábamos que era lo que habíamos hecho durante el tiempo que no nos habíamos visto. O dicho de otra manera, se trataba de responder a la pregunta del cliente: "¿Qué han estado haciendo con mi dinero?".

Como carecíamos de dotes adivinatorias, frecuentemente lo que hacíamos no era lo que el cliente esperaba y comenzaban las peleas, la típica asignación de culpas con analogías:

- ¡Esto es como hacer una casa sin ventanas!
- Pero si querés ventanas me lo tenés que decir.
- Es obvio, si en una casa va a vivir gente necesita ventanas.
- Los bunkers no tienen ventanas y son construidos para que viva gente en ellos.

Bueno, la historia conocida por todos.

Así, desde mi primer contacto con un proyecto de software (o algo parecido) comenzó a ser evidente la ineludible necesidad de conocer y gestionar los requerimientos.

Creo que la importancia de saber definir qué se debe construir antes de hacerlo es algo conocido por cualquier profesional que tenga algo de experiencia por lo que no puede existir mucho espacio para debatir en este sentido. La controversia surge cuando se comenzamos a pensar: ¿cómo lo hacemos?, ¿cómo definimos qué debemos construir?

La especificación de requerimientos es una de las actividades que, a mi entender, tiene una relación más fuerte con la documentación en la mente de las personas que se dedican al desarrollo de software. Percibo que existe una sensación que la manera de medir que tan bien se está realizando esta actividad es proporcional a la cantidad de documentación de requerimientos que se genera.

Esta bien, todos sabemos que se pueden hacer malos documentos y que se puede perder mucho tiempo inútilmente cuando no se saben escribir, pero es difícil encontrar alguien que piense que se puede llevar adelante un proyecto de desarrollo profesionalmente si no se documentan extensivamente los requerimientos.

Alistair Cockburn dice en un artículo:

"...escribimos esos documentos de especificación y diseño como si realmente pudieramos explicar completamente que queremos decir. Y no podemos. Nunca podemos aspirar especificar completamente los requerimientos o el diseño. No tenemos la menor de las posibilidades. Cuando escribimos, asumimos que el lector tiene un cierto nivel de experiencia. Si podemos asumir más experiencia, entonces podemos escribir menos. Si tenemos que asumir menos experiencia, entonces tenemos que escribir más."

Software Development as a Cooperative Game, Alistair Cockburn

Cockburn profundiza la presentación del concepto en en el borrador de su libro "Crystal Clear" (http://members.aol.com/humansandt/crystal/clear/):

"Las personas que hablan entre ellas para comunicar ideas, necesariamente usan referencias de experiencias en común. Esto debe ser así, de hecho, no existe otra forma de comunicarse. Las personas con las experiencias compartidas necesarias entienden la comunicación, las otras no.
...La ventaja [de esta característica de la comunicación] es que los desarrolladores de software pueden acotar las descripciones de lo que están haciendo acudiendo a la extensiva experiencia compartida con sus compañeros. Esto les permite moverse más rápido."

Quien lleve un tiempo desarrollando seguramente habrá experimentado esta ventaja. ¿Cuántas veces hemos participado de un dialogo como el siguiente? :

- Juan, ¿no te acordas si en algún lado habíamos hecho una clase de búsqueda para el XML de seguridad de la versión vieja?
- Si, Carlos, creo que hay algo en el sistema del gobierno para la importación a Meta4. Fijate en la carpeta Varios, creo que por ahí estaba la dll y el código.

Este dialogo esta lleno de referencias a experiencias compartidas. Juan y Carlos saben que es "una clase de búsqueda para el XML de seguridad de la versión vieja", "en el sistema de gobierno para la importación a Meta4" y "la carpeta Varios".
Este tipo de conversación sería imposible entre dos personas sin experiencias compartidas. En ese caso la conversación tendría que ser más específica, detallada y lenta. Cockburn continúa:

"...esto no es algo que se pueda evitar. No es como se piensa, que escribiendo casos de uso los desarrolladores entenderán repentinamente los requerimientos. Los desarrolladores que leen los casos de uso deben tener un conocimiento adecuado en el vocabulario del negocio para entender lo que están leyendo. Si ellos tienen un conocimiento amplio, entonces los casos de uso pueden ser más cortos y anecdóticos... La especificación no es una especificación a menos que los lectores la entiendan."

Es interesante pensar como pueden afectar nuestra manera de valorar los requerimientos las connotaciones de esta última frase.
Karl Wiegers define algunas características de requerimientos excelentes. Entre ellas:

"Completo: cada requerimiento debe describir completamente la funcionalidad ha ser entregada. Este contiene toda la información necesaria para el desarrollador para diseñar e implementar esa funcionalidad..."

"Sin ambigüedad: Todos los lectores de una especificación de requerimientos deben llegar a una única y consistente interpretación de esta."

Writing Quality Requirements, Karl Wiegers

Si tomamos como ciertos los comentarios de Cockburn, podemos concluir que es imposible que estas sean características intrínsecas de los requerimientos. La completitud y ambigüedad variara según el lector.

Por eso una especificación puede carecer de ambigüedad, ser completa, y a la vez ser breve, para un lector o grupo de lectores en particular. La brevedad me resulta una característica muy valorable en una especificación de requerimientos, donde se aproveche al máximo las experiencias compartidas de las personas que se tratan de comunicar a través de esta especificación.
Saber que es lo que se debe construir no implica necesariamente escribir un extenso documento. Muchas veces no es la mejor manera de hacerlo aunque sé que en muchas situaciones es la manera posible, aceptada, o habitual. Y por eso pienso que documentar requerimientos no es una regla básica que se tenga que cumplir, aunque conocer las necesidades y definir las soluciones si lo es.

Muchas veces se plantea como un cambio difícil de lograr el que requiere dejar el caos para comenzar a desarrollar software aplicando buenas prácticas. Creo que un cambio igual de difícil es replantear esas buenas prácticas a la luz de los objetivos y pensar que pueden existir alternativas que merecen ser consideradas.