El estudio

es poco ambiguo al respecto: “los equipos con documentación de calidad están más capacitados para implementar prácticas técnicas y funcionar mejor en su conjunto”. Entre otras cosas, son 3,8 veces más propensos a tener buenas prácticas de seguridad informática y es 2,4 veces más probable que alcancen consistentemente sus objetivos de negocio. La buena documentación no sólo facilita el día a día y hace más fácil y agradable el trabajo, también está ligado de forma estadísticamente significativa a un mejor rendimiento del equipo. Puedes pasarle esa cita y esos números a tu jefe. Sin embargo, esta no es la experiencia habitual en entornos profesionales de desarrollo de software. Con frecuencia, la documentación suele ser pobre, incompleta y a menudo desfasada, si es que existe para empezar. Y cabe preguntarse por qué es tan frecuente ignorar una práctica que intuitivamente es evidente que es beneficiosa y para la que ahora tenemos evidencia estadística. La tesis de este texto es que culturalmente la documentación no se valora.

Y al decir que no se valora se quiere decir que no se valora de verdad. Por supuesto es agradable encontrarse con un sistema bien documentado, y cuando alguien por su buena voluntad decide invertir tiempo y esfuerzo en documentar suele recibirse con agradecimiento, qué menos, pero esto no quita que estructuralmente el trabajo de documentación esté enormemente menospreciado. Esto significa que en muchas empresas la existencia de buena documentación depende del heroísmo individual de desarrolladores que deciden a contracorriente documentar su trabajo, a pesar de la falta de ayudas y de incentivos. El problema del heroísmo individual es que no escala, ni en el tamaño del equipo ni en el tiempo. Es improbable que todas las personas de un equipo estén concienciadas sobre la importancia de la buena documentación y dispuestas a hacer ese trabajo por pura voluntad, e incluso si se da el caso, es improbable que siga siendo verdad conforme gente se va de la empresa o nueva gente entra en el equipo. Por otro lado, requerir a una persona un esfuerzo extra sin ningún incentivo es insostenible a largo plazo. La persona termina por quemarse y decidir que ese esfuerzo no merece la pena. Por eso es necesario, si un equipo quiere tener buena documentación, que se establezcan la cultura y los procesos necesarios para que esta documentación pueda ser creada sin exigir demasiado del equipo. Valorar la documentación no significa solamente apreciarla cuando ya está hecha. Significa entender que merece la pena pagar un coste para que se haga y se mantenga.

Este texto explora tres apartados en los que se puede mejorar: producción, organización de la documentación y, el más importante de todos, educación.

En cuanto a producción, sería muy fácil decir que el problema simplemente está en que no se asigna tiempo a documentar, o por lo menos no como regla general. Si un desarrollador dice que necesita un día más para documentar su trabajo, de repente el mundo recuerda que la documentación existe y todo el mundo dirá que estupendamente y que adelante. De nuevo, el problema del heroísmo individual. Si el desarrollador no demuestra interés personalmente, nadie tiene en cuenta a la hora de planear el tiempo para documentar, por lo que no se planifica y no se hace.

De todas formas, esta visión es simplista y sólo ve los síntomas del problema. La solución no consiste en mover a producción el trabajo de acordarse de que la documentación existe. Eso sería mover la responsabilidad, no reducirla. El problema es que la documentación no se ve como un entregable. No se exige como parte del trabajo, no se versiona, no se revisa por pares para ver si es de calidad. Todas esas prácticas de desarrollo que se han elaborado para el código y de las que se tiene constancia de que son beneficiosas, por alguna razón no se aplican a la documentación. Si la documentación no se espera que esté, lo normal es que no esté. Si no va a estar sometida a escrutinio, lo normal es que esté hecha con mayor dejadez. Si no se establecen mecanismos adecuados para evaluar su vigencia, lo normal es que se quede desfasada.

Otro de los problemas frecuentes de la documentación es encontrarla. Es frecuente que la documentación de un equipo consiste en un enorme árbol de páginas de Confluence al que se va añadiendo nuevas páginas un poco donde se le ocurre a uno que pueden encajar. Con frecuencia hay poco sistema a la hora de organizar la documentación, y el decidir dónde ubicar una página nueva consiste más bien en intuición y ojímetro. Esto significa que a menudo es difícil encontrar documentación incluso cuando existe, lo que puede llevar a una espiral descendente. La gente no busca documentación cuando tiene un problema, así que no está acostumbrada a interactuar con la documentación en el día a día y a valorar su importancia, por lo que no le da importancia cuando es su turno de documentar.

La organización de la documentación requiere de empatía hacía la persona buscándola. Hay que entender las diferentes necesidades por las que una persona podría estar buscando documentación sobre un sistema, y organizar el árbol de páginas de forma que guíen naturalmente a esa persona de acuerdo a sus necesidades. Esto también requiere de organización, de un sistema que estructure la información de forma que donde colocar una página nueva no sea una cuestión de intuición sino de seguir el sistema. Por último, es importante mencionar que empatizar con el lector no es una habilidad mágica innata con la que uno nace, se estudia.

No deja de ser curioso el hecho de que se asuma que todo el mundo sabe escribir documentación. Uno va a la universidad donde tiene varias asignaturas de informática para aprender a programar, y continúa educándose a lo largo de su vida leyendo artículos y papers y viendo charlas, las entrevistas de trabajo evalúan la habilidad del candidato programando no vaya a ser que no sepa, pero por lo que sea escribir documentación es algo que no se estudia, no se aprende, no se practica, simplemente uno lo tiene. Has aprobado lengua castellana y literatura en la ESO, ¿no? ¡Pues hala, a escribir! Pero lo cierto es que saber escribir no significa saber escribir. Me explico, saber juntar letras en un texto escrito gramaticalmente correcto no significa que ese texto sea inteligible, informativo, útil ni agradable de leer. Como cualquier otra habilidad, escribir es una habilidad que se aprende, y que se mejora a través de la práctica, por supuesto, pero también de estudiarse y aplicar la teoría.

Sin embargo, en ningún momento del desarrollo de un ingeniero de software, ni de la mayoría de carreras en realidad, existe formación dedicada para desarrollar la habilidad de escribir. Tampoco es muy probable que uno vaya a cruzarse con el mucho y muy buen material que existe sobre cómo escribir mejor documentación, y si lo hace es probable que se pase por alto. Aquí juega de nuevo el factor cultural de que la documentación es algo de segunda, y que naturalmente uno dedica su tiempo libre a leer sobre lo que le gusta, no necesariamente lo que le vaya a venir mejor.

Por supuesto, es muy ingenuo pensar que una persona sin los conocimientos va a aprender a documentar solamente con la práctica. Aprender requiere práctica dirigida, aplicación intencionada de los conceptos teóricos y crítica constructiva para aprender qué mejorar. Nada de eso va a suceder en un grupo de personas en el que nadie sabe ni quiere aprender.

La falta de conocimiento no sólo afecta a la calidad de la documentación. También afecta a la cantidad. A la hora de enfrentarse a una tarea, la falta de conocimiento crea un problema de seguridad psicológica, ya que la persona encargada de llevar a cabo esa tarea no tiene la confianza ni la seguridad en sí misma para hacerla. También es más probable que la exposición a ser criticada por un mal trabajo produzca miedo o rechazo. Esto significa que en muchos equipos la tarea de escribir documentación produzca una sensación de rechazo, dependiendo de la persona entre hastío y pavor. Como en muchos equipos la documentación no se exige, sino que depende de la buena voluntad de cada uno, esto lleva a que sea más probable que la documentación simplemente no se escriba. Como tampoco se revisa ni se somete a crítica, cuando sí se escribe es frecuente que se haga lo mínimo para cumplir. Educar al equipo en buenas prácticas a la hora de escribir no sólo aumenta la calidad de lo que escriban, resultado ya beneficioso en sí mismo, sino que aumenta su seguridad a la hora de escribir y su propensión a querer hacerlo y querer hacerlo bien.

Como explica el estudio antes mencionado, los equipos con buena documentación rinden más. Sin embargo, en muchos equipos hay problemas estructurales que impiden que la documentación de calidad y abundante surja de forma natural como parte del proceso de desarrollo. Sin cambios estructurales a la forma de funcionar, la presencia de buena documentación depende del heroísmo individual de los miembros del equipo, que por definición va a ser inconsistente y frágil. En este texto hemos presentado tres aspectos en los que un equipo puede mejorar para en última instancia mejorar la cantidad y calidad de la documentación que produce. Entre las tres, cabe destacar que la educación es la más importante y

del resto.