Artículo originalmente publicado en dotNetMania.
La documentación siempre es un aspecto que exige nuestra atención en los proyectos de software. A menudo tendemos a pensar que la mejor manera de lograr que nuestros proyettos avancen y poder mostrar ese avance es realizando la documentación adecuada, buscando el ciclo adecuado para esa documentación y estableciendo una serie de documentos como estándares. Incluso hay metodologías bastante populares que se centran en definir qué documentos se deben generar, quién es el responsable de cada documento y por qué manos debe pasar cada uno de ellos. ¿Nos olvidamos de que los documentos no se pueden ejecutar? ¿Nos olvidamos de que el propósito final de todo proceso de desarrollo es conseguir software que funciona?
A menudo,de la documentación que mantenemos durante el desarrollo solo un pequeño porcentaje tiene valor para el cliente. Es cierto que habitualmente hemos de entregar cierta documentación, manuales de operación, de administración o de usuario; esta documentación tiene un claro valor. Este tipo de documentación se debe tratar como cualquier otro entregable. En el fondo, ésta es la única documentación que es realmente imprescindible, la que el destinatario del software necesita, aquella por la que, hipotéticamente, estaría dispuesto a pagar. Minimizar la documentación que no aporta nada a nuestros clientes, que solo sirve para soportar nuestro proceso de desarrollo, y sobre todo el coste de mantenerla, debe ser uno de nuestros objetivos.
El avance de los proyectos de software es algo que siempre ha preocupado a todos los implicados en los mismos. Es algo sobre los que nuestros clientes centran su interés y algo que, como gestores de proyectos, necesitamos comunicar. Tradicionalmente hemos abordado esta necesidad de mostrar el progreso mediante el uso de diferentes documentos o artefactos. Todos los que hemos tenido que mantener actualizado “el project” del proyecto sabemos lo difícil que esto es. Es tan difícil, que rara vez se hace con la disciplina que requiere, de tal modo que habitualmente este tipo de aproximación no proporciona los resultados esperados.
El enfoque tradicional de mostrar el avance de los proyectos mediante documentos es algo que no funciona bien. Nuestros clientes han descubierto que los documentos rara vez nos muestran el avance real de un proyecto. Es muy posible haber trabajado mucho y tener una gran cantidad de documentación sobre un proyecto y estar a años luz de que quien financia el proyecto pueda obtener valor. ¿Quién no conoce algún proyecto en el que tras muchos meses de desarrollo lo único que había es un montón de documentos? Los documentos por sí mismos no aportan ningún retorno de la inversión. No se puede hacer nada para obtener valor para tu negocio solamente con la documentación relacionada con un proyecto de software. Solo el software que pueden ejecutar y utilizar es susceptible de crear valor para nuestros clientes. Solo el software que funciona debe ser la medida del progreso de los proyectos de desarrollo. Asumir esto nos obliga a asumir que tendremos que entregar software con frecuencia a nuestros clientes, que tendremos que reaccionar de manera ágil al feedback que nos proporcionen y que a cambio ellos obtendrán de manera temprana un retorno para su inversión.
Debemos ser muy tacaños con el esfuerzo que ponemos en nuestra documentación; si no, corremos el riesgo de ver que todos aquellos requisitos, por poner un ejemplo, que tan detalladamente documentamos sobre el sistema de gestión que nuestro cliente quiere, son papel mojado porque han comprado una nueva unidad de negocios. Y nosotros ya hemos hecho un gasto del que difícilmente obtendremos algún retorno. La documentación en los proyectos de software pierde su relevancia y se queda obsoleta muy rápidamente, haciendo que mantenerla actualizada sea muy costoso. A menudo cometemos el error de tratar de sustituir la comunicación fluida por documentación, y cuando hacemos esto, estamos introduciendo costes e inflexibilidades en nuestro proceso de desarrollo.
Otro aspecto del desarrollo de software que nos lleva a generar documentación es la necesidad de mantener los sistemas que desarrollamos. Se suele pensar que la documentación detallada del sistema nos va a evitar un montón de quebraderos de cabeza. Pero esto solo es cierto si esa documentación cumple la premisa de estar actualizada. Cuando un desarrollador encuentra una línea en la documentación que no es correcta o no está actualizada rápidamente pierde la confianza y vuelve su vista a la única fuente de verdad absoluta: el código fuente. Esto nos lleva a la situación de que solo la documentación que se genera directamente desde el código fuente de manera automatizada tiene verdadero valor.
El código es la única fuente de verdad absoluta sobre un proyecto de software a nivel de detalle, y el nivel de detalle es el único útil para modificar, extender o mantener un sistema en producción. La documentación directamente asociada al código fuente o embebida en él (comentarios que permitan generar documentación, por ejemplo, con NDoc, JDoc o similares) o aquella que se genera de manera automática desde el mismo (por ejemplo, diagramas de clases que solo son otra vista del código) es la que más valor tiene, pues evoluciona y se mantiene en paralelo al código fuente y siempre está actualizada.
Otra documentación que no está directamente relacionada con el código fuente y que es de gran utilidad, si no imprescindible, es la relativa a arquitectura. Es necesario que un nuevo desarrollador o aquel que resucita el proyecto tras un tiempo puedan comprender qué decisiones de alto nivel guiaron el desarrollo. Esta documentación sirve para comprender por qué se tomaron determinadas decisiones que no se cambian con facilidad a lo largo del proyecto y proporciona una primera aproximación de alto nivel. La arquitectura de una aplicación no suele cambiar a menudo; lo que cambia más frecuentemente es la implementación, el código. Esta documentación es simple de mantener, porque es mucho más estática que la de diseño detallado.
A menudo nos centramos en documentar olvidando que la principal fuente de información sobre qué hace una pieza de software está el nombre de los componentes, de las clases y de las funciones. La principal documentación con la que contamos es el estilo de nomenclatura, la coherencia a la hora de nombrar cosas y una arquitectura general coherente. Establecer un lenguaje común, la nomenclatura y el estilo que va a guiar del desarrollo es más valioso que cualquier documentación. Mucha documentación puede emanar de una serie de patrones que se repiten a lo largo del proyecto, tanto a nivel arquitectónico como de diseño, y estos patrones donde viven es en el código.
Buscando valor para el cliente, cada vez más proyectos deciden mantener una base de conocimiento sobre nuestro proyecto, basada en artículos cortos y con ejemplos, tipo knowledge base, sobre los que se pueda realizar búsquedas fácilmente. Por eso se están popularizando tanto como repositorios de información sobre proyectos los wikis: no imponen una estructura, son ágiles de mantener, fácilmente actualizables, fácilmente buscables y soportan muchos tipos diferentes de contenido.
También se tiende cada vez más a sustituir la documentación por la refactorización: si una pieza de software es compleja, tenemos dos posibles estrategias a la hora de hacerla entendible. La primera es documentarla; la segunda es, a base de refactorización y de mejorar el diseño, simplificarla para hacerla más clara. Se puede ganar mucho en la legibilidad de nuestro software simplemente eligiendo buenos nombres, evitando las funciones enormes, limpiando las variables no utilizadas… La ventaja de este enfoque es que mejora objetivamente el software, haciéndolo más mantenible y más claro, sin necesidad de un artefacto externo que puede fácilmente quedar desactualizado.
Antes de escribir cualquier documentación debemos preguntarnos varias cosas: ¿Es realmente imprescindible? ¿Será fácil de mantener? ¿Aporta algún valor claro para nuestro cliente?
El manifiesto ágil resume lo aquí expuesto de la siguiente manera: “El software que funciona es más importante que la documentación exhaustiva”. El desarrollo de software va sobre código fuente y ejecutables, no sobre documentos.
Me alegro Rodri de que este artículo lo hayas puesto aquí.
Estoy totalmente de acuerdo. El problema de la documentación es que nunca (repito el nunca) es un espejo fidedigno del resultado final obtenido (del Software).
El empleo de las KB o de las Wikis se está extendiendo mucho como bien dices. El conocimiento fluye y queda ahí, para que sea accesible a todos, se pueda leer y se pueda contribuir.
¿Quien no se imagina un documento mal redactado o explicado porque simplemente no se ha tenido en cuanto algún aspecto que otro integrante del proyecto sí ha tenido?. Volvemos entonces a otra parte que muy indicas, la documentación como tal, crea barreras de comunicación muy importantes que hace que el proyecto no continúe como se espere.
No quiero extenderme que sino repito tu entrada, pero contaré una anécdota que me pasó hace tiempo en un proyecto. Me tocó documentar el inicio del proyecto y el documento que escribí ocupó cerca de 50 páginas. El gerente miró el documento y lo que me dijo sin ni siquiera leerlo fue: «Este documento pesa poco. Añade más cosas porque al cliente hay que darle algo que tenga más páginas.»
Mi pensamiento fue: «¿Que quieres?, ¿que diga las cosas concisas y directas y sea fácil de leer para cualquiera, o que pese diga las cosas con rodeos y nadie se lo lea nunca?.
Evidentemente, con documentaciones así, mejor usarla como pisapapeles y mirar el código que será más ameno, y si encima documentamos el código con comentarios XML, mejor que mejor.
Abrazotes titán.
Siempre unos de los principales " karmas " de los desarrolladores ha sido la documentación
Existe una linea bien marcada entre lo que es documentar el producto de trabajo y lo que es documentar la gestión de ese trabajo.
En el segundo caso, a mi entender el más polémico, solo se trata de trazabilidad y control y muchas veces se pierde el horizonte tratando de tener todo totalmente controladito y perfecto para poder responder con evidencia suficiente hasta la última pregunta inquisidora de los managers o el auditor. Entonces el esfuerzo del equipo se centra en mantener coherencia y trazabilidad en todas las actividades: carga de horas, matrices de trazabilidad, decisiones planteadas en reuniones y sus minutas, aprobaciones, documentos de requerimientos, analisis, diseño, auditorias anteriores, post-mortems, revisiones de código, predicción de errores, planes de QA, de gestión de configuración, de costos, bla, bla, bla.
Por otro lado, la documentación del producto de trabajo es más flexible, aunque puede estar alcanzada por alguna política especial que nos restrinja. Yo creo que si es un software al estilo «software copmo servicio» con unos esbozos sobre la arquitectura puede alcanzar, mientres que si es un producto que se va a vender muchas veces de manera «customizada» con esto no alzanza y hay que documentar mucho más, incluso hay que confeccionar hasta el manual con el que se van a capacitar a los desarrolladores «customizadores».
En cuanto a los comentarios en el código; que decir, me parece una idea muy mala, basta ver los documentos hechos con jDoc que se encuentran en la red para darse cuenta que son pura basura. La mejor especificación es el propio código fuente y si algo parece necesitar un comentario, lo que realmente necesita es codificarse mejor.
Perdón por extenderme tando 🙂
No estoy de acuerdo con lo que dice el articulo, muchas vecez las compañias cambian de personal y si las aplicaciones no tienen una buena documentacion el mantenimiento y los cambios que se deben hacer a las aplicaciones se vuelve tediosa y recurre en mas tiempo y dinero para la compañia, ademas la falta de documentacion genera desconfianza y muestra la falta de madurez de una compañia
Carlos C, la documentación no ayuda para nada en los cambios. Más bien los entorpece… hay que cambiar también la documentación no solo el código. Un buen código, coherente, bien organizado, y con test unitarios pero sin documentación es mucho más facil del cambiar y extender que uno incoherente, mal organizado y sin tests… por mucho documentación que este último tenga.
Sobre lo de que la documentación sea sintoma de madurez, perdoname que discrepe. Que haya documentación no garantiza que esta sea fresca, que este actualizada, que corresponda con el código, que sea mantenible, o que sea útil…
Sobre la desconfianza… nada genera más desconfianza que el código de mala calidad y la documentación poco actualizada.
De cualquier modo yo no hablo de no tener documentación en absoluto, sino de tener la justa, generarla automáticamente y tener claro que la dcoumentación no sustituye al software ejecutable… el valor intrinseco de la documentación para el cliente es casi nulo y esto a menudo se olvida.
Yo creo que la documentacion depende mucho del tipo de desarrollo y organización en la que se trabaja. En mi caso particular con una lista de requerimientos, una breve especificación tipo Use case y un modelo de datos es suficiente.
Lo que si tratamos es que el codigo sea lo mas autocomentado posible mediante el buen nombramiento de variables, procedimientos, metodos, funciones, parámetros, etc
Pero eso no significa que esto le pueda servir a otro.
Siempre digo y pienso que hay que hacer un balance… si algo no me agrega valor y solo me quita tiempo… no lo hago.
Hay un buen paper que habla sobre el documento de requerimientos como un manual de usuario.