Mejores prácticas de documentación para equipos de datos

¿Por qué tanta importancia a la documentación?

En ixpantia creemos que la documentación es la base de un buen productos de datos. Y no nos referimos a documentar solamente qué hace el producto como tal, para nosotros es igual de importante documentar el proceso que llevó a él. Creemos tanto en ella que consideramos que documentar es un pilar esencial del ethos de ixpantia de compartir conocimiento. También es parte de nuestro ethos el generar las capacidades en nuestros clientes, y el dejar productos muy bien documentados es esencial para lograr esto.

Pero a la misma vez conocemos que en la práctica la documentación que escribimos tiende a estar desfasado a lo que tenemos en desarrollo o producción. Requiere de una cultura donde tenemos el espacio para recordanos repetidas veces entre nosotros que hay que documentar!

En este blogpost queremos compartir las 6 mejores prácticas de documentación que hemos definido y que rigen nuestro día a día.

1. “Big picture” amerita una imagen o diagrama

Cuando estamos documentando un proceso complejo y de múltiples partes o bien, explicando un sistema o infraestructura, usar diagramas ayuda al lector a ver el panorama completo fácilmente. Es mucho más sencillo para la persona lectora ver cómo se interconectan las partes o elementos entre sí que tratar de imaginarlo mientras lee. Por eso, invertir un tiempo extra en crear este tipo de diagramas puede ahorrar mucho tiempo posterior en preguntas o en malos entendimientos de un proceso o infraestructura.

2. Documentación en un lugar central y notas lo más cerca del proceso posible

Si estás documentando un proceso, trata de escribir notas lo más cerca del lugar donde el proceso corre, ya sea en el mismo código o en un lugar similar si la herramienta lo permite. Sin embargo, estas notas no son sustituto de una documentación extensa que explica todo el proceso, en un lugar central, donde pueda incluirse documentación de los diferentes elementos.

Un ejemplo de este último son los Wiki en un repositorio en github, cada script puede contener comentarios en el código y además creamos una documentación de como interactúan los scripts entre ellos dentro del wiki.

3. Documentación describe el impacto en el negocio, notas describen detalles de su ejecución

En la documentación central, explicamos los pasos tomados, desde la perspectiva del negocio, para llegar al resultado, no es solo una traducción del código a palabras. El enfoque debe ser porque se hacen las cosas, no como se hacen nada más.

En las notas escribimos más detalles de lo que se hace y cómo se aplica, sobretodo si son pasos que se derivaron de una discusión o situación especial

4. Define conceptos (documentación ayuda a crear un marco de referencia común)

Es importante incluir definiciones en la documentación de un producto de datos. Especialmente si son conceptos específicos del área de negocio que pueden no tener ningún sentido para quienes no son parte de ella. Cuando escribas documentación piensa en personas que no tienen tu mismo contexto y formación, que pueden entenderlos de forma distinta.

5. Mejor escrito a medias que no escrito del todo

Si no tienes el tiempo o recursos para documentar algo en su totalidad, trata de dejar al menos unas notas o un resumen corto. Es mejor que haya al menos algo de documentación para la siguiente persona use como punto de partida a no documentar del todo.

Es importante aprovechar los momentos de desarrollo o muy cercanos a la finalización de un proceso con datos porque tenemos los conceptos, elementos y lógica frescos, si no tienes tiempo de hacerlo hacerlo de forma extensiva, aprovecha esa frescura del tema para dejar al menos un par de notas escritas que incluso te puede funcionar como punto de referencia para ti mismo en el futuro, cuando tengas tiempo para documentarlo correctamente.

6. Todo suma, NADA es superfluo, aún si crees que es obvio

Cuando estas creando un producto de datos te puede parecer que algunos detalles son “demasiado obvios” como para necesitar documentarlos, sobretodo si has sido parte de todo el proceso de desarrollo.Sin embargo, recuerda que para nuevos miembros que tu equipo no lo va a ser, incluso tú mismo en el futuro puedes necesitar que te refresquen estos conceptos y/o procesos. Entonces documenta todo detalle posible, es mejor tener documentación de sobra que luego se puede limpiar a que pasen meses y eso que era obvio dejó de serlo y por ende el uso o entenmiento del producto de datos se ve afectado.

Pensamientos finales

Si tu día a día involucra crear, manejar o incluso usar productos o procesos con datos, documentar también tiene que serlo. Documentar no es una pérdida de tiempo, al contrario, te libera tiempo en el futuro. Tanto las personas con las que trabajan, como usuarios o stakeholders van a agradecer mucho tener el producto o proceso bien explicado de principio a fin, esto ayuda a la toma de decisiones y a crear confianza en lo que has creado.