archivo

Archivo de la etiqueta: documentación

Cuando se documenta es necesario tener presente el período de caducidad del documento. Si hay documentos que se pretenden que sean la referencia del producto desde diferentes puntos de vista: funcional, operativo, arquitectura, diseño, etc… es importante tener en cuenta hasta dónde llega nuestra capacidad de ir manteniéndolos conforme el producto evoluciona.

Ser demasiado ambicioso implicará muy probablemente que buena parte de esa documentación deje de actualizarse y por tanto esté caducada a efectos prácticos (incluso se puede dar el caso de que la misma perjudique más que ayude). Sin embargo resulta difícil encontrarnos con casos en donde un documento se tache como caducado siendo la única referencia la fecha real de elaboración o aprobación del mismo (si es que efectivamente aparecen por alguna parte).

La documentación debe ser la realmente necesaria (que no es lo mismo que la teóricamente necesaria) y acorde a lo que podamos soportar. Sobre esa premisa cada cual dentro del enfoque que considere más adecuado para el proyecto que decida qué es lo que realmente necesita (salvo que existan procesos donde más allá que de un mínimo te impongan una serie de hitos documentales).

Creo que la siguiente reflexión de Bertrand Meyer (profesor universitario y autor francés, experto en programación orientada a objetos y creador del lenguaje Eiffel) resume el contenido de este artículo: “Hay una situación peor que no tener documentación y es tener documentación incorrecta”.

Una cosa es la documentación propia del proceso de desarrollo de la cual ya sabéis mi opinión (actual): debe proporcionar valor real a quien va dirigida y debe ser la justa y la necesaria acorde al contexto del proyecto y a las características del sistema de información (más documentación de la necesaria o, siendo necesaria, más información de la que resulta práctica es un peso muy importante con el que cargar en el proyecto y que termina derivando generalmente en documentación que se queda obsoleta y que generalmente no ha amortizado el esfuerzo que ha sido necesario para elaborarla y mantenerla hasta el momento en que se decide abandonar).

Hay determinados sistemas que su principal misión es proporcionar servicios a terceros o servir de plataformas que se configuran y/o son ampliables para contener en ellas diferentes tipos de aplicaciones. En estos casos la documentación necesaria para integrarse u operar con ellos debería ser algo innegociable y el esfuerzo en mantenerla con la mayor calidad posible y actualizada un objetivo prioritario dentro de este tipo de sistemas. En caso contrario el esfuerzo necesario para que los desarrolladores investiguen cómo trabajar con esas herramientas se multiplica prácticamente tantas veces como integraciones o desarrollos se realicen sobre ellas lo que al final deriva en esfuerzo que ha podido ser perfectamente evitado (y en dinero que se podía haber ahorrado o esfuerzo que se podía haber invertido en mejorar en lo posible las funcionalidades más importantes del sistema) y que se puede considerar como un interés a pagar por la deuda de esa falta de documentación.

Se documenta muchas veces “por imperativo legal”, es decir, porque nos lo pide el cliente y/o porque nos lo piden nuestros propios procesos.

Hacer la documentación de esa manera, con tan poco cariño, no suele dar buenos resultados ya que se hace para cubrir el expediente y no se cuida que realmente sea útil.

Documentar por documentar no sirve de nada, documentar tiene sentido si aporta un valor.

Como os he comentado en diversas ocasiones vengo de una formación en enfoques clásicos y de trabajar en proyectos con metodologías clásicas en los cuales la documentación es el elemento común en todas las fases del proyecto. De la documentación generada solo suele ser útil una porción de la misma (se sobredocumenta para justificar que se cumplen con los hitos y por otro lado la calidad deja mucho que desear y eso que en los enfoques clásicos la documentación no es un elemento extraño sino que de convivir con ella se considera parte esencial del proyecto) y de ella gran parte de su valor se va perdiendo conforme se evoluciona el producto (si con la misma no se actualiza la documentación).

En enfoques clásicos la documentación como engranaje en las distintas etapas del desarrollo tiene su utilidad, sin embargo otra cosa bien distinta es que realmente sea la base sobre la cual se desarrolla porque incluso en este tipo de enfoques los requisitos y las especificaciones cambian en etapas tardías y estos cambios no se suelen llevar aparejadas actualizaciones en la documentación (suelen quedar recogidos en actas de reunión en el mejor de los casos). A esto hay que sumar lo comentado en el párrafo anterior en donde la orientación a cumplir el proceso suele dar lugar a una documentación cuya calidad no suele ser proporcional al esfuerzo puesto en ella.

Cuando es el propio proceso el que sobredocumenta el proyecto, el desarrollador realizará ese trabajo adicional sin ganas, sin cariño (como decía al principio) e impacta sobre la calidad de la documentación que podría tener utilidad.

La documentación tiene valor cuando encuentra un lector que encuentra utilidad en la misma. Eso es importante. Muchas veces se documenta para un lector futuro que nunca llegará o que cuando llega es tan tarde y la aplicación habrá cambiado tanto (o lo suficiente) que no se amortizará el esfuerzo de haberlo realizado.

La documentación es un instrumento, también se utiliza en las metodologías ágiles, de hecho las historias de usuario, las pilas de producto, etc… son documentación (en las que los procesos y/o los desarrolladores le dan la formalidad que estiman conveniente) por tanto su valor o no va más allá del enfoque del proyecto y está relacionado, como decía antes, con la utilidad real que tenga y su alcance y estrategias de actualización dependerán de las características del sistema que se desarrolla y del contexto del proyecto (y estará muy condicionada por el proceso o procesos de desarrollo si se establecen directrices relacionadas con la documentación).

La comunicación entre las personas es una herramienta muy potente que siempre ha estado ahí y que los procesos se han encargado de dejar en un segundo plano por la visión formalista que se le ha dado tradicionalmente a los mismos. Ese formalismo situó a la documentación como elemento que dinamiza el desarrollo (engranaje lo llame antes) cuando la dinamización debe ser cosa de las personas que intervienen en el proyecto. Si la documentación se convierte en una herramienta más y no en el centro del proyecto es posible (y así es efectivamente) que cada documento se centre exclusivamente en sus objetivos (prescindiendo de contenido de escaso valor para el lector) y que haya documentos (de trámite) que sean innecesarios.

Una iteración no se debe considerar completa si no se ha realizado un testing del mismo nivel de detalle que se exigiría a si el incremento fuese a pasar a producción (hay que tener en cuenta que la finalización de un sprint puede dar lugar a una nueva versión en producción o no).

Si no hacemos eso vamos a ir arrastrando deficiencias a través de las iteraciones y en donde el coste de subsanarlas irá creciendo conforme vaya incrementándose la deuda técnica. Y, además, muy probablemente, el número de errores que lleguen a producción será mucho mayor.

No es real considerar que has implementado una historia de usuario si no has probado de manera efectiva que hace lo que tiene que hacer.

También hay quien considera que no es completa si no cumple otras características como, por ejemplo, que tenga el mismo nivel de documentación que si se produjera una entrega real a producción. En este caso no puedo pronunciarme objetivamente porque dependerá mucho de las características del proyecto, si bien, soy de la opinión de que sí que resulta interesante tener documentada cada historia de usuario que se implementa, al nivel que sea necesario en el proyecto, para el resto de documentación, tal y como comentaba antes, dependerá del proyecto y sus circunstancias.

¿Es compatible generar documentación de un proyecto con la aplicación de principios ágiles? Partiendo de la base de que la agilidad está por encima de las metodologías, por supuesto que sí. Ahora bien, si bajamos el nivel y nos ponemos a nivel de métodos o estrategias ágiles mi opinión es que también, si bien habría que tener siempre en cuenta el contexto del proyecto y el tipo de documentación requerida (en ocasiones la exige el cliente según los procesos que tenga establecidos).

En un enfoque iterativo incremental cada evolución tendrá como objetivo realizar una serie de tareas (pila de sprint) que forman parte de un conjunto de tareas más general (pila de producto). Estas tareas pueden ser de distinta índole: construcción, refactorización, testing, configuración de entornos y, ¿por qué no? Documentación que sirva de base para próximas iteraciones (además de documentación que puede ser de utilidad para el mismo sprint, como por ejemplo documentación de entrega del producto que servirá para su instalación, testing, etc… realizado por personas ajenas al equipo.

Desde esa perspectiva sí que es posible generar documentación siguiendo estrategias o metodologías ágiles si bien hay que entender que la excesiva formalización de la documentación (más de la que el proyecto necesita) supone una resistencia para la evolución del producto: más tiempo para documentar, menos tiempo para desarrollar (y no más documentación supone un mejor desarrollo ya que no se trata de cantidad sino de calidad).

Yo soy partidario de que cada funcionalidad a desarrollar se trabaje de manera que tanto usuarios como programadores sepan qué se va a hacer, ¿estrategia? dependerá del proyecto, de los usuarios, del esquema de trabajo, etc… muchas variables. La historia de usuario supone un instrumento que me gusta bastante: trabajo la historia, aplico técnicas de prototipado si es preciso, no es importante la formalidad y sí el contenido, lo importante es que quede claro lo que se quiere hacer. ¿Habrá huecos en la definión? Es posible, preguntemos lo que sea preciso y decidamos si actualizamos o no la historia en función de la respuesta.

¿Qué hacemos con la historia de usuario tras su construcción y tras la iteración? Es importante registrar lo que se ha hecho en cada iteración y no supone mucho trabajo registrar la historia de usuario asignada a cada tarea.

Opiniones sobre esto hay una por cada desarrollador que existe ya que incluso en visiones parecidas puede haber matices más o menos sensibles. Hay quienes prefieren aplicar ingeniería de requisitos (esto nos lleva hacia metodologías más clásicas si bien es compatible con enfoques iterativos e incrementales) y en el otro extremo historias de usuario de usar y tirar. Cada cual aplica sus conocimientos y experiencia al contexto del proyecto, lo importante es satisfacer las expectativas del usuario y hacer un producto de calidad y mantenible, lo demás son instrumentos, con mayor o menor importancia, pero instrumentos al fin y al cabo.

Hace poco un amigo me contó que tuvo que hacer una recopilación de documentación de un proyecto de tamaño medio/alto donde gran parte de la misma tenía una antigüedad de entre dos y tres años.

Me dijo que le resultó desolador comprobar como cientos y cientos de páginas tenían una utilidad nula en el presente y como tantas y tantas horas de esfuerzo dieron lugar a un sistema de información que se encontraba a años luz de las expectativas que tenían puestas los usuarios. ¿Qué hubiera pasado si ese esfuerzo se hubiera enfocado en otras actividades que hubieran resultado de mayor utilidad?.

Como mínimo es algo que merece una reflexión, por un lado para saber si merece la pena perder mucho tiempo en aspectos formales de documentación que poco después probablemente no sirva, para llegar a la conclusión de que solo hay que documentar lo que de verdad pueda proporcionar valor al proyecto (y nada más) y para demostrar que una documentación aparentemente buena no tiene por qué dirigirnos hacia un sistema exitoso.

La siguiente reflexión de Brian Marick no deja indiferente: “Los documentos del proyecto son una ficción interesante: útiles, pero nunca suficientes”.

Este es un tema controvertido en el que como es lógico existirán opiniones para todos los gustos y probablemente casi todas tengan su parte de razón.

Siempre hay detalles que no recoge la documentación (el proyecto es algo vivo y está sujeto a cambios y a nuevos matices) y hacer que recoja todos los detalles puede requerir un esfuerzo importante tanto para el documento en sí como en futuras actualizaciones del mismo (tal vez y ya es mucho decir, se consiga cerrar una documentación completa y de calidad de una versión del producto, mantener esto resultará complicado y de la misma manera que el software, la documentación “se deteriorará” con el tiempo).

Soy de la opinión (estoy convencido) de que el programador no debe inventar nada cuando está desarrollando pero eso es una cosa y otra que los detalles que no aparecen en la documentación deban aparecer reflejados finalmente en la misma ya sea de manera formal o informal (habrá situaciones donde resulte interesante (o rentable) y en otras no).

El testing exploratorio se centra en el producto y, por tanto, va más allá de la documentación del proyecto y el uso que se hace de la misma es el de un instrumento para comprender mejor la aplicación y para obtener información que pueda ser de utilidad para el testing. Consultas al equipo de desarrollo, al área usuaria y la revisión de la propia aplicación e incluso del código proporcionarán un mayor nivel de conocimiento.

No rechazo la documentación, no quiero que se entienda así, rechazo el exceso de formalidad y el exceso de documentación. Es un instrumento, no lo olvidemos, cuando se convierte en un fin, creyendo que a través de ese fin se consiguen los objetivos, tenemos un problema.