archivo

Archivo de la etiqueta: documentación

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.

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

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.

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ónarrojar 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).

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

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.

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.