Frederick Brooks. La documentación y la visión global del sistema

Comenta Frederick Brooks en su libro «The Mythical Man Month» que: «La mayoría de la documentación falla en que se da muy poca visión global. Se describen los árboles, se comentan la corteza y las hojas pero no hay un mapa del bosque».

Estoy bastante de acuerdo con esa afirmación ya que resulta complejo obtener una visión global del sistema simplemente con la lectura de la documentación del proyecto porque como dice Brooks la información está segmentada y se describe con más o menos detalle cada uno de esos segmentos pero no el funcionamiento en conjunto de todos ellos.

Y todo esto en el caso de que haya alguien que revise la documentación de manera más o menos concienzuda, porque esa es otra, se pueden invertir innumerables horas de trabajo en tratar de hacerla con la mayor calidad posible, pero al final hay personas que tienen que leerla y entenderla y no suele haber gente con mucho tiempo y/o paciencia para iniciar sobre ella un proceso iterativo de revisión y mejora.

Esto es un problema importante cuando se desarrolla basado prácticamente en exclusividad en la documentación y no se suple esa carencia a través de la comunicación con personas que puedan ofrecer la información necesarias para cubrir los huecos en la misma lo que provoca generalmente problemas de coherencia en el sistema y aspectos funcionales a los que el desarrollador da una solución sin entender realmente qué lugar ocupa esa funcionalidad dentro del sistema.

La solución, como comento en el párrafo anterior, es la comunicación y además (y en lo posible) en explicar lo que tiene que hacer el sistema y las expectativas del usuario a quien no haya tenido la oportunidad de conocerlo, algo que generalmente (y desgraciadamente) no se suele hacer.

Desarrollo de software. La documentación no debe sustituir a la comunicación

Cuando se elabora una documentación, como por ejemplo un catálogo de requisitos o una historia de usuario, se parte de una persona o grupo de personas que comunican en ese instante su visión del producto, de una funcionalidad o de una característica (se trata de una concepción abstracta por lo que ahí ya hay una diferencia entre lo que realmente necesitan y en lo que creen que necesitan), esa visión es transcrita por una persona o por un grupo de personas desde la interpretación que hacen de las mismas (por lo que también se pierde información), teniendo en cuenta que en el propio proceso de pasar esas ideas a lenguaje escrito también se pierden matices.

Esa documentación posteriormente es interpretada por las personas que la leen, por lo que, si nos ponemos a analizar, hay una diferencia (en unos casos más sensible que en otros) entre lo que se quiere y lo que se interpreta finalmente, y el documento, aunque deja constancia por escrito del trabajo que hay que realizar, es un elemento que introduce ruido sobre el objetivo final.

Por tanto, el documento no debe sustituir a la comunicación, sino que es en todo caso un instrumento en el que debe apoyarse la misma. Es un error pretender que los documentos sustituyan a la relación entre las personas porque de ser así, perdemos información, perdemos precisión y existirá desviaciones entre lo que se quiere y lo que se obtiene finalmente.

Todavía más duro resulta en contextos cambiantes o en productos que por sus características o complejidad requieran un feedback continuo del usuario, ya que resulta complicado dar una respuesta adecuada si tenemos que estar trabajando exclusivamente con pesados documentos que van de aquí para allá.

Agilidad, ¿dónde queda el conocimiento del proyecto?

La agilidad no consiste en no documentar. Cada proyecto tendrá sus propias peculiaridades y necesidades, no obstante en la mayoría de los casos lo que sí puede variar es ese enfoque tradicional de la documentación orientado a la utilización de soluciones ofimáticas por otro soportado por herramientas colaborativas y/o CASE.

En cualquier caso y sea cual sea la estrategia que utilices y/o requiera el proyecto (no siempre estarán alineadas) lo que sí es importante entender es que el conocimiento de un proyecto debe ir más allá de la documentación, de hecho debería considerarse en un segundo nivel con respecto a lo que debe suponer el principal objetivo que no es otro que el conocimiento esté distribuido en el equipo, de manera que cada cual sepa qué papel juegan las tareas que realiza tanto en el proyecto como en el producto, consiguiéndose de esta manera una mayor eficacia y una reducción de la dependencia respecto a determinadas personas.

Puede que no parezca el camino más corto pero a la larga el número de kilómetros que se recorren con este tipo de estrategias es mucho menor.

Es razonable que unos sepan más que otros en determinados aspectos pero la visión general debe ser compartida (independientemente de que existan diversas percepciones) y la particular, al menos, conocida, no debiendo quedar ningún elemento estratégico o crítico en manos de una sola persona. Este tipo de situaciones, en las que se crean parcelas de conocimiento (que al fin y al cabo es poder), no solo suponen un riesgo desde el punto de vista de la continuidad de determinadas tareas o de capacidad de adaptación al cambio sino que terminan por fracturar a los equipos.

Agilidad, documentación, protección

Cuando trabajamos desde una actitud ágil aplicando prácticas, estrategias o metodologías ágiles, tendemos a centrarnos en el incremento del valor del producto, sin olvidarnos de tener una deuda técnica sostenible, mientras solemos dejar de lado algunas tareas de gestión que llegado el momento nos pueden ahorrar algún problema.

Partamos de la base de que la agilidad funciona en un marco de trabajo en el que existe confianza entre las partes, cuanto mayor sea la separación entre las personas y los equipos más dominará la metodología y la burocracia y menos la agilidad (antipatrón «arrojar al otro lado del muro«), sin embargo a veces en los proyectos intervienen factores externos que terminan por afectar a su desarrollo normal produciéndose problemas.

Por ejemplo, una de las partes cambia sensiblemente su posición en el proyecto exigiendo alcances o incrementos de presupuesto, siendo la situación del proyecto tal que no es posible alcanzar un acuerdo sin que alguna de las partes ceda de manera considerable.

En esos momentos, por muy buena voluntad que sigamos teniendo los que estamos en las trincheras tanto por parte del cliente y del proveedor, el partido se suele jugar en otras instancias, las cuales empiezan a solicitar a los equipos evidencias para tratar de utilizarlas en el proceso de negociación (o confrontación), evidencias que no irán más allá en muchos casos que el contenido de la pila de producto o de los sprints, lo que será insuficiente y luego se empezarán a pedir explicaciones por determinados tipos de acuerdos verbales que no se han registrado por escrito.

¿Cuál es la solución? Puedes optar por aplicar una táctica defensiva en todos los proyectos o realizar ajustes en función del mismo. La táctica defensiva consiste en tratar de registrar documentalmente todos los acuerdos parciales en el proyecto sin salirnos de la línea base del acuerdo inicial, esto puede servir como coraza (aunque quien quiera liarla, la liará con esto y sin esto).

Una táctica que considero más adecuada al desarrollo ágil consiste en analizar realmente qué tipo de proyecto estamos realizando, qué exigencias tiene nuestra organización y cuál es nuestra experiencia con el proveedor o con el cliente y a partir de ahí tomar tus propias decisiones sobre qué debe tener evidencia documental y que no (además de estas evidencias la propia metodología o procesos de las organizaciones pueden imponer otras, que tendrás que seguir quieras o no).

La documentación como justificación de los trabajos

Soy de la opinión de que la documentación en los proyectos no debe ser extensa, debe centrarse exclusivamente en lo que necesita el proyecto y la organización dentro de sus procesos internos y nada más.

A veces son los propios procesos organizativos los que extienden el número y el tamaño de los documentos, cuando eso sucede y el beneficio de esa actividad es inferior que la inversión que hay que realizar para llevarla a cabo es cuando hay que plantearse si efectivamente los procesos están bien definidos.

Hablo de beneficio en general no de un proyecto concreto, ya que las organizaciones deben tener una vista más panorámica, si bien resulta fundamental que cuando un proyecto requiera excepciones debidamente justificadas se deba ser lo suficientemente flexible.

¿Por qué a los niveles superiores de la organización les gusta tanto la documentación? Porque con documentación parece que hay un orden y que las cosas se hacen bien. ¿Cuántas veces se ha justificado el trabajo en un proyecto en base a la documentación por encima del valor real que tiene el producto? y eso es así porque cuando estás alejado del día a día de los proyectos y no se sabe de qué va realmente el mismo y las diferentes contingencias que se han producido durante el proceso de desarrollo, se entiende a evaluar por lo que se entiende (equivocadamente o no) y el peso de la documentación se suele entender como síntoma de que se ha trabajado (otra cosa es que sea más o menos efectivo y que la documentación tenga el nivel de calidad y actualización necesario para que realmente sea útil).

¿Establecer plazos para la documentación?

Es razonable definir plazos. De hecho si aplicamos sprints, éstos tienen una fecha de finalización.

La metodología definida en una organización puede exigir la entrega de determinada documentación asociada al proyect sea o no documentación que resulte necesaria para el trabajo a diario en el proyecto.

Puede ser deseable que los ítems necesarios para el proyecto puedan cubrir las necesidades de la organización pero en cualquier caso, quien se encarga de definir los procedimientos de trabajo es el que tiene que valorar el coste de exigir determinada documentación que se puede considerar adicional a lo que se está necesitando.

Lo que veo todavía más discutible es el hecho de exigir plazos a una documentación dentro de un sprint. Sí que puedo entender que se fijen fechas tope y que el equipo de proyecto pueda jugar con ellas, pero exigir fechas concretas para cada uno de ellos dentro del sprint me parece excesivo y contraproducente.

Hay que entender a la organización y sus procesos, pero no debemos olvidar que el fin último de cada proyecto es entregar un software de calidad y la documentación no es condición necesaria ni suficiente para ello.

Jeff Patton. Conocimiento sobre documentación

Comenta Jeff Patton que: «No necesitamos una documentación precisa, sino un conocimiento compartido».

Esa reflexión no descarta la documentación si bien no le da el monopolio sobre el conocimiento porque la documentación es eminentemente estática y el conocimiento es dinámico, porque la documentación presenta como límite la habilidad del redactor y la comprensión del lector y el conocimiento se basa más en la comunicación y en la interacción, si algo no lo he entendido lo consulto, si en algo no estoy de acuerdo trato de fundamentar otra posible solución (sin menospreciar la base teórica o informativa de los documentos escritos).

Los documentos se pueden utilizar como interfaz entre diferentes grupos de trabajo (siempre y cuando sus actividades no requieran una interacción continua o frecuente o la misma no sea posible, independientemente de que sea deseable), sin embargo, no se debe cometer el error de restringirlo como único canal de comunicación, precisamente por el hecho de que resulta prácticamente imposible que toda la información se haya plasmado adecuadamente y que el propio lector consiga interpretarlo con la misma intención que la persona que lo redactó (todos sabemos que existen tantas percepciones o visiones sobre un determinado asunto como observadores haya).

Por mucho tiempo que se dedique a la redacción del documento, siempre se va a perder información y se van a alimentar los malos entendidos. Cuando se requiere la colaboración continua entre personas o entre equipos, este modelo no funciona.

No hace mucho un amigo me hizo referencia a un proyecto de hace ya algunos años en el que la comunicación entre usuarios y desarrolladores se basaba principalmente en documentos (también existía diálogo, pero la pieza fundamental, eran encuestas, formularios, etc…), ¿podéis imaginaros cuál fue el resultado del proyecto?.

Por otro lado si la interfaz se basa en documentos, se alimenta la distancia entre los equipos, propiciando la aparición del antipatrón «arrojar al otro lado del muro«, en el que el proyecto queda en segundo plano, ante la actitud defensiva que toman los diversos implicados.

Bertrand Meyer. El problema de la documentación que no es válida o es incorrecta

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».

Desarrollo de software. Plataformas, proveedores de servicios y documentación

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.

Desarrollo de software. El valor de la 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.