Cómo documentar tu proyecto de software

🧐 Contexto

Hace poco leí la una frase que dice algo así: "Escribe un artículo de lo que te gustaría encontrar cuando buscas acerca de un tema en Google" así que siguiendo esta premisa voy a compartir con ustedes mi siguiente artículo 👀

Donde trabajo actualmente tenemos una sección mensual denominada Math.random() (a mi me gusta decirle Matemática Aleatoria) donde DEVs nos juntamos a compartir un rato nerd, hacer learn injections, exponer algún tema interesante, o comer sanguchitos de miga y charlar.

Recientemente me brindaron la posibilidad de exponer una pequeña charla acerca de documentación de proyectos. El entusiasmo me llevó a escribir este artículo con algunas opiniones, recomendaciones, buenas prácticas y algo más. Ojalá te sirva para tus proyectos!

🤔 El problema

Una de las principales cosas que me llamaron la atención al preparar la presentación, fue intentar definir qué significa documentar, me topé con lo siguiente en Wikipedia: "La documentación es la ciencia que consiste en documentar".

La cantidad de artículos relacionados es abismal, artículos muy buenos, muy detallados, que abarcan cada una de las etapas de un proyecto, con explicaciones de cómo documentar para metodologías waterfall y agile, diferenciar los tipos de documentación dependiendo si el target es un sector técnico, de marketing, usuario, etc. Momentos en los que se debe documentar y en los que no. En fin, sin duda la cantidad de contenido es increible y muy profesional.

Pero aún teniendo todo este material, seguí sin encontrar lo que estaba buscando, me tomé unos minutos y dije:

F*CK OFF (ノ°▽°)ノ︵┻━┻

😅 Las 4 excusas DEV para no documentar

Lo que buscaba es una forma práctica de recomendar cómo o por qué documentar y motivar al resto del equipo a que también lo haga. Reconociendo el problema intenté basarme en mi experiencia y determinar por qué alguien DEV no documentaría un proyecto de software. Entonces detecté que puede haber 4 excusas potenciales para no hacerlo.

• Es aburrido: Documentar literalmente no es divertido
• No es prioridad: Siempre va a ser mas importante resolver un bug, trabajar en un nuevo feature, etc
• Se desactualiza rápido: Por la naturaleza evolutiva de un proyecto de software, si no se mantiene la documentación, puede quedar obsoleta muy rápido
• Nadie lo lee: Muchas veces no todo el mundo está al tanto de lo que está docuemntado.

Pero si estas cuatro son excusas ciertas y totalmente válidas, ¿por qué estoy tratando de convencerte de que es importante documentar?

😱 Riesgos por no documentar

Bueno, resulta que no documentar un proyecto tiene ciertos riesgos que pueden ser problemáticos, molestos y costar tiempo o dinero. Basandome en mi experiencia detecté que podrían existir 3 riesgos principales relacionados con el tiempo y la información.

• Riesgo 1: El mayor riesgo de no documentar es tener que hacerlo cuando no tenés tiempo ni recordás nada.
• Riesgo 2: Puede perderse información valiosa por olvidarse de algo importante o por simple rotación de DEVs.
• Riesgo 3: Perder demasiado tiempo buscando solución a un problema ya conocido.

OK, hasta ahora tenemos un montón de excusas para no documentar y varios riesgos que podrían existir por no hacerlo. ¿Entonces que debería hacer como DEV para evitar estos problemas?

😎 Establecer prioridades prácticas

Entender el problema nos pone en contexto y hace que comencemos a organizar la información en nuestro cerebro de tal forma que eventualmente podamos establecer las prioridades adecuadas para ir proponiendo soluciones viables a los problemas que vimos anteriormente. Lo que me lleva a hacer la siguiente recomendación:

Una mínima documentación es más viable que prometer la mejor documentación que nunca vas a escribir.

Vamos a dividir el proceso y prioridades de documentación en 3 partes para que puedan ser útiles y prácticas.

1. Documentar lo básico (MVP)

Un problema muy común cuando solicitas ayuda, o cuando hacés un onboarding a algún compañero/a de equipo es que esa persona no tenga forma de levantar o hacer correr el proyecto sin tener al menos algún tipo de problema por desconocimiento o falta de información. Por eso es muy impotante y es básico de cualquier proyecto que tenga documentado estas 3 características, no existen excusas para que no lo hagas.

1. Comandos para levantar o correr el proyecto
2. Variables de entorno necesarias para establecer una configuración inicial o similar
3. Preguntas frecuente a problemas comunes.

2. Extender el detalle de la documentación

Ya documentado lo básico, hay que pensar en los términos a mediano y largo plazo (más de 4 meses). Cuando se empieza a trabajar en el proyecto y hay varios equipos involucrados en el desarrollo (ej: un equipo frontend y otro backend) es muy importante que ambos equipos esten sincronizados, que conozcan como se está construyendo el software, entender y estar al tanto de los datos que se transfieren de un equipo al otro, etc. Por eso considero que en este punto es indispensable al menos documentar los siguientes tres puntos:

1. Arquitectura del proyecto (front, back, infra) indicando quién es el responsable de cada área o proceso. (Recomiendo documentarlo como un diagrama de flujo o similar)
2. Contratos entre el backend y el frontend.
3. Decisiones tecnológicas, librerías, frameworks y herramientas utilizadas.

3. Centralizar la información del cliente

El último paso para comenzar a tener una documentación sólida es centralizar la información que se obtiene del cliente en el proyecto. Una Wiki debería usarse como "la fuente de la verdad" un lugar centralizado donde encontrar información útil para cualquier miembro del equipo.

1. Accesos y credenciales a herramientas, VPN, etc.
2. Datos de ambientes del cliente (ej: servidores, plataformas, IPs, etc)
3. Material de seguimiento y seguridad (tracking IDs scripts para Google Analytics, Hotjar, reCAPTCHA, etc)
4. Documentación visual de componentes (frontend) o tests de integracioens (backend)

😮 ¿De qué me sirve documentar?

Ahora que definimos las 3 prioridades que te pueden ayudar a iterar la documentación a lo largo de la construcción de tu proyecto. Me gustaría explicar por qué es importante documentar, para qué sirve o definir cuál es el propósito.

1. Documentar ayuda a tus compañeros/as de equipo a tener una visión global del proyecto, reafirmar el conocimiento sobre áreas poco relevantes.
2. Ayuda a que los equipos esten sincronizados y se evitan dependencias de personalidades del equipo, por ejemplo recurrir a determinadas personas continuamente para obtener información relevante.
3. Proporciona un ahorro y optimización de tiempo ya que al tratar la documentación como una fuente de la verdad, solo hay que ir a buscar la información allí y utilizarla.

🤩 Tips & Tricks

Me gustaría mencionarte algunos otros consejos que me parecen importantes para que apliques a tu documentación.

Precauciones a tener en cuenta

1. La documentación es una herramienta viva, no hay que permitir que se desactualice. Dedicarle tiempo al menos 1 vez cada dos semanas o cuando sea necesario.
2. Documentar lo importante en archivos (ej: README.md, CONTRIBUTION.md) asi pueden migrar junto con el proyecto y no quedan separados en una Wiki o similar.
3. No asumir por entendido lo que nos parece obvio ya que no tenemos los mismos seniorities ni pertenecemos a las mismas áreas.

Debe entenderse por sobre todo

1. La documentación debe ser lo mas práctica y directa posible, evita párrafos extensos, aburridos y burocráticos.
2. Usar emojis ayuda mucho a referenciar visualmente una sección o ítem. Cuando estamos trabajando en varias tareas al mismo tiempo o tenemos la cabeza en otra actividad de mayor importancia, los elementos visuales son de gran ayuda.
3. Usar índices en la parte superior de la documentación provee una mejor experiencia de uso. Si leer una documentación es costoso y aburrido, al menos intentemos hacer que sea lo más ameno posible.

📌 Conclusiones

1. Sean prácticos, directos y prolijos
2. Sean explícitos pero no aburridos ni burocráticos
3. No dejen la documentación para la última etapa del proyecto.
4. Traten a la documentación como un "bonsai de software"

Recordá siempre intentar agregar valor a todo lo que hagas como dev en el lugar en donde trabajes.

¡Muchos éxitos!