La creencia popular suele asociar documentación con aburrimiento, no es que se pueda decir que documentar es la parte más creativa del desarrollo sin embargo poca gente se da cuenta de las bondades ocultas de la documentación. En este artículo voy a comentar algunas que es posible mucha gente no se haya dado cuenta así como algunos consejos para hacerlo más ameno (sí, es posible).

Una de las razones principales que no hay que olvidar sobre la documentación es que más allá de su utilidad o necesidad se realiza también por un concepto de solidaridad, todos hemos entrado por primera vez en una empresa y nos hemos enfrentado a un proyecto del que no sabemos nada, siempre se agradece que alguien se haya acordado de esa gente que entra nueva en el proyecto y haya preparado una documentación con la que empezar para no tener que golpearse contra una pared o estar preguntando cada 5 minutos.

Herramientas

Hay muchas herramientas para documentar, no me voy a detener en ellas porque no es el propósito de este artículo pero en general con el tiempo si me he dado cuenta que es más cómodo trabajar con aquellas herramientas de edición en línea tipo blog como puede ser Confluence o Github que otras estilo Sharepoint en las que creas un documento con una tercera herramienta (como un Word) y luego lo subes a la plataforma, las razones son varías:

• Necesitas herramientas de terceros que pueden no ser gratuitas, además necesitas que estén instaladas en el equipo que estés usando, normalmente siempre será el mismo pero puede que necesites hacer un pequeño cambio con un móvil o tablet.
• Es más incómodo porque hace falta tener varias herramientas abiertas a la vez, por ejemplo un Word y la web de Sharepoint, lo cual produce cierta pereza a la hora de generar documentación.
• Por la misma razón para editar hay que abrir el Word y bajarse el archivo para editarlo y volverlo a subir, o que el navegador permita abrir la aplicación embebida en el navegador, si lo soporta, en general no es muy directo y cómodo.
• Discrepancias de estilo, documentación hecha por varias personas con varios formatos, si se hace en línea es fácil ver que los formatos no son coherentes y es más fácil aplicar herramientas automatizadas.
• Los diferentes ficheros pueden ser de diferente tipo Word, Excel… lo que complica mucho la búsqueda y también la explotación de la información.
• A no ser que se haga con cuidado (y esto suele llevar mucho trabajo y detalle) los documentos se acaban versionando (mal) por nombre y se acaba teniendo Manual-1.0, Manual-2.0, etc… al final es fácil perder la pista de cual es el último o cual hay que modificar y se acaba llenando la aplicación de ficheros, es mejor editar el mismo documento y tener un historial para poder ver los cambios, las versiones anteriores y poder comparar.

Esto no quita que la herramienta deba permitir visualizar cualquier fichero, por ejemplo a veces un vídeo o una presentación pueden ser útiles. En este caso verlas directamente desde el navegador sería la opción preferida.

Pero independientemente de cual sea, una buena práctica es mantener siempre esa aplicación o web abierta, para que en cualquier momento simplemente saltando a esa aplicación se añada un comentario o se haga una pequeña corrección. Para simplificar esto la aplicación debe de tener un índice y debe de ser fácil encontrar lo que se quiere modificar o actualizar de tal forma que con un par de clicks te coloque en el sitio que necesites para actualizar el contenido y después continúes con tu trabajo.

Algunos extras interesantes que suelen tener ya presentes muchas plataformas es la opción de insertar comentarios, ya sea directamente en los textos como anotaciones o en una sección aparte -usualmente en la parte inferior-, con esto último hay que tener cuidado ya que la página se puede hacer excesivamente grande debido a los comentarios, generalmente esta sección es mejor usarla para perfiles que no tengan permisos para editar el documento.

Otros detalles como una sección de feedback o la posibilidad de recibir notificaciones cuando el contenido se ha actualizado también suele ser bastante útil.

Costumbres

Realmente la documentación no esconde grandes secretos es sobre todo una cuestión de practicar y para eso es bueno coger una costumbre, por ejemplo escribir pequeñas cosas durante el día a cierta hora o apuntarlas aparte y al final de un sprint -si se usa agile- o cada cierto tiempo dedicar un rato a escribirlas en la documentación.

La palabra documentar tiende a generar cierto agobio porque cada uno piensa en todo lo que tiene que escribir (es decir, todo lo que no ha documentado que tenía que haber documentado) y se le cae el mundo encima, no es necesario abarcarlo todo, sino empezar por pequeñas cosas, como si fueran pequeñas funciones de programación, solo que en este caso explican una concepto determinado o una idea y poco a poco con el tiempo todas esas piezas van encajando para construir un documento más completo.

En esta línea no hace falta inicialmente -sobre todo si no hay ninguna documentación o no se tiene experiencia y/o ganas- volverse loco con frases o palabras o como escribirlo, es mejor simplemente ponerse a escribir, a medida que se escribe se van viendo las formas de cambiar el texto para que quede mejor. La idea es escribirlo aunque no sean grandes documentos, al menos que quede reflejado.

Las costumbres se pueden coger de varias formas, por ejemplo en un despliegue a producción si no hay ningún documento que explique el proceso se puede ir realizando mientras se desarrolla el despliegue así se tiene un documento verificado y actualizado del proceso. Otro caso podría ser durante una reunión de equipo, si hay una charla para explicar un nuevo concepto o idea en lugar de decirlo o dibujarlo malamente en una pizarra o papel se pueda dibujar en un PowerPoint o similar y usar ese mismo PowerPoint como punto de entrada a una documentación más elaborada.

Finalmente una buena costumbre es actualizar la documentación cuando se detecta una discrepancia, generalmente no suelen ser grandes cambios -porque si lo fueran es mejor directamente crear un documento nuevo- pero permite mantener la documentación actualizada, en este sentido es bueno coger la práctica de que cualquier persona que detecte esa discrepancia tenga la capacidad de poder cambiarla y no delegar esa responsabilidad en una tercera persona que puede no tenga tiempo de hacerlo en ese momento y correr el riesgo de que al final ese cambio se pierda y no se haga.

Escribir no es pintar

Una buena opción es, primero escribir y luego estructurar, es más fácil estructurar porque al fin y al cabo no es más que copiar y pegar los textos ya escritos en un sitio u otro y darle forma y esa forma de trabajar es más afín a la mentalidad de un desarrollador que simplemente escribir hojas y hojas con principio y final que es más un trabajo literario.

Por ejemplo, se puede documentar simplemente un proceso de subida a producción y otro día documentar el proceso de desarrollo, con el tiempo esas secciones se pueden ir homogeneizando dándoles un formato similar y finalmente crear un elemento padre que sea Despliegues en entornos.

Es verdad que aunque la idea no es crear un libro escribir documentación si requiere un cierto trabajo literario pero sobre todo más en el sentido de ser capaz de explicar las cosas de tal forma que cualquiera las pueda entender aunque sea un texto técnico, en lugar de escribir código para desarrolladores que sea fácil de entender y mantener, la idea es escribir texto que sea comprensible por un mayor grupo de personas y esto es interesante porque en cierta forma cuando hay que escribir documentación para personas no técnicas ayuda a entender como esos perfiles ven la aplicación.

En este sentido no es malo documentar para escapar un poco de la disciplina del código y practicar otras habilidades, en un momento de ofuscación puede ser una vía de escape para hacer otra actividad diferente, y si hay que realizar una presentación documentar ayuda a asentar las ideas e ir practicando como se va a explicar una aplicación.

Depurando por escrito

Una de las mayores ventajas que he encontrado en documentar es que es mucho más fácil encontrar tus propios errores y también descubrir las cosas que no sabías y las posibles lagunas que puedes tener, a fin de cuentas documentar es como explicarte a ti mismo lo que has hecho y como lo has hecho y en ese proceso es fácil darse cuenta de errores, imprecisiones o duplicidades que habrá que corregir en código o incluso fallos de concepto.

De hecho una forma de descubrir que el código tiene buena calidad es al documentar, una documentación imprecisa o larga y tediosa y que no surge fluida y es difícil de entender suele ser un síntoma de que la aplicación puede tener fallos conceptuales o ser innecesariamente complicada, esto ayuda a simplificar el código por ejemplo detectando piezas de código que ya no son necesarias. Funciona igual en el sentido inverso, al escribir código uno se puede dar cuenta de que la documentación es incorrecta yendo entonces a actualizarla o sino hay tiempo en ese momento simplemente marcarla como inválida o moverla a otra sección a la espera de que más adelante se pueda arreglar.

Es interesante también de cara a una nueva funcionalidad, si una idea que se pretende desarrollar es complicada de documentar, explicar o crear ejemplos en base a ella es un claro síntoma de que puede que no sea una buena idea, quizás es demasiado complicada (idea feliz) o demasiado arriesgada (mejor empezar con algo más terrenal).

Finalmente…

Sobre los idiomas, esto es es muy dependiente del proyecto y de la empresa pero la costumbre generalizada suele ser documentar en inglés que para mucha gente suele ser una razón más para no hacerlo pero también puede ser una razón más para meterse en el idioma, no solo para entenderlo mejor sino también para asimilar y aprender nuevos términos en inglés que son útiles de cara al desarrollo, por ejemplo para buscar información o usar una mejor nomenclatura.

Es curioso que mucha gente diga que no tiene tiempo para documentar pero si para explicar lo mismo a varias personas, es más rentable escribirlo como si se lo estuvieras contando a alguien que repetirlo varias veces, de hecho una forma de comprobar que se entiende es dar ese documento a alguien y si es capaz de aplicarlo satisfactoriamente con las mínimas preguntas es que el documento es util.

La famosa frase la virtud está en el término medio se puede aplicar también aquí, tiene tan poco sentido documentarlo todo como no documentar nada, en un lado no documentar nada no es útil pero documentarlo todo no es práctico porque harían falta constantes correcciones y se invertiría demasiado tiempo, es fácil que al final la documentación acabase siendo un pequeño monstruo de imprecisiones y desactualizado que nadie quiera modificar.

Como medida subjetiva una o dos veces por sprint suele ser suficiente, puede que al principio se haga más pero tampoco dedicarle demasiado tiempo, hay que tener en cuenta que un código bien hecho también ayuda, además el código siempre cambiará más y más rápido que la documentación así que no tiene sentido documentar código como tal. En general la documentación debería responder a la mayoría de las preguntas pero el objetivo no es responder a todas las preguntas.

Espero que todos estos consejos ayuden a todos aquellos reacios a documentar y vean las bondades de la documentación más allá de la manida frase de es algo que hay que hacer.