Documentar Software no es tan Difícil

Muchísimos chistes se han contado sobre lo poco o nulo que suele ser la documentación en proyectos de software. Si bien la documentación de librerías populares muestra la gran dedicación que le ponen el equipo de mantenedores, cuando miramos al software dentro de las empresas en las que trabajamos es cuando padecemos de la carencia de una documentación decente.

Que falte documentación puede ocurrir por diversas causas, desde falta de tiempo, negligencia, desinterés o desmotivación (porque caduca muy rápido) hasta desconocimiento de cómo hacerlo o incluso qué documentar.

En realidad, documentar es sencillo. Hay muchas formas de documentar y no necesariamente hay que buscar la más compleja ni usarlas todas al tiempo. Empezar gradualmente, documentando asuntos críticos o piezas clave dentro de un software, será suficiente para poco a poco ir adoptando esta importante práctica.

En los siguientes párrafos voy a contar algunas formas que he usado y/o que me parecen interesantes y buenas guías a seguir cuando se quiera documentar o empezar a hacerlo.

Primeros Pasos

Para empezar, considero que de la forma más sencilla para practicar documentar es valerse de herramientas que generan HTML a partir de comentarios en el código. Por ejemplo, en Ruby es muy popular YARD y RDoc.

También es bueno documentar decisiones en el código aún cuando no se esté generando una página. Hay decisiones muy complejas que no se pueden leer con el código o que se pueden perder en el historial de commits. ¿Qué mejor que un comentario para reflejarla?

Otra forma es valernos de herramientas que convierten formatos como Markdown a páginas HTML muy elegantes y profesionales. De esas herramientas puedo destacar Docusaurus, Read the Docs y Postman.

Las anteriores son una especie de bases para empezar. Ahora vayamos un poco más allá.

El código no es lo único a documentar

Si bien lo más importante en todo proyecto de software es el código e idealmente debería estar bien documentado, no es lo único que se puede documentar o necesita documentación.

¿Qué otras cosas se pueden documentar? Es muy común ver en proyectos de código abierto los archivos README. Aquí se puede dejar información básica y clave del proyecto con respecto a configuraciones, cómo es el flujo de trabajo en Git, el modelo de datos, herramientas preferidas, etc.

El README es un libro abierto y se puede complementar con otros READMEs organizados en subcarpetas del proyecto.

Al respecto existe este proyecto llamado “El Arte del README” el cual sirve de guía para tener idea que colocar en este tipo de documento.

Otra cosa a documentar, sea que la hagas en un README o de una forma más especial, es el flujo de trabajo con Git o el sistema de control de versiones usado en el equipo.

Todos los equipos son diferentes y la forma en que se usa Git puede variar un montón. No está demás que todos los miembros tengan esta información clara y accesible en alguna parte del repositorio. Mejor aún cuando llegan nuevas personas al equipo porque ya está ahí documentado.

Documento la integración con frontend, el flujo Git y enlazo a procesos particulares.

El modelo Entidad-Relación definido para la base de datos es documentable. Sea que lo tengas dibujado en papel (montas la foto en el repositorio) o usas una herramienta como MySQL Workbench para graficar y exportar a PDF o JPG, al final resultará muy útil tener una alternativa visual para entender cómo se almacena la información en el proyecto que trabajas.

Los procesos particulares que tenga el software también son claros candidatos a documentar. El código dice muchas cosas y en general explica cómo pasan las cosas en el software pero a veces el por qué se nos escapa.

Siempre va a haber cosas particulares que pasado el tiempo y leemos alguna clase o algunas líneas de código nos surgen muchas preguntas y a veces las respuestas son “eso fue algo que pasó en ese entonces y nos tocó hacer eso pero no recuerdo que era“.

Lo mejor que uno puede hacer como desarrollador de software es, cuando se encuentre con esas situaciones, es escribirlas en algún lado. Donde sea. Hay que anotarlas. No deberíamos tener excusa.

¿Qué hago yo? En los proyectos en los que trabajo pasan muchas cosas raras y he aprovechado para practicar lo anterior. Para ello me valgo mucho de Dropbox Paper. Podría bien documentar esos casos en la misma tarjeta de Jira pero sé que ahí se va a perder la información. En Dropbox Paper tengo un documento en blanco donde puedo escribir usando un formato sencillo(markdown) e incrustar imágenes e incluso código.

Documentación en Dropbox Paper

Luego, pasado el tiempo y el documento está más conciso o ya sea el momento, lo exporto a markdown y lo pongo en la carpeta docs del proyecto. De esta forma, por un lado tengo el documento original a mí alcance y también está compartido con el equipo en caso de ellos necesitarlo.

Después de varios años trabajando y encontrarme estos casos, además de propiciarlos, decidí que era hora de cambiar eso y mejorar mis habilidades a la hora de documentar. Ha valido mucho la pena porque ya no hay tanta información en la oscuridad.

Por supuesto que no es fácil. Hay que siempre buscar el espacio para escribir las cosas que pasan, a veces me toca dejar el código “tirado” para poder escribir el por qué de algo antes de que se me olvide o me toca sacar 10 o 15 minutos para recordar y escribir porqué hice una cosa de este modo o reuniendo enlaces para que el documento quede bien armado.

¿Vale la pena? Claro que vale la pena. Hay que esmerarse a escribir buen código pero el desarrollo de software no es solo código, hay un montón de cosas que lo complementan y siempre busco hacer lo mejor posible en cada responsabilidad.

Anímate a empezar a documentar. Hay muchas formas y no tienes que hacerlas todas al tiempo. Vas a ver que vale la pena.

Enlaces relacionados:

Autor: cesc1989

Ingeniero de Sistemas que le gusta escribir y compartir sobre recursos que considera útiles, además que le gusta leer manga y ver anime.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Salir /  Cambiar )

Google photo

Estás comentando usando tu cuenta de Google. Salir /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Salir /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Salir /  Cambiar )

Conectando a %s

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios .