Documentación perrona

Imagínense que entran a trabajar a un proyecto que lleva en producción mas de 5 años, con muchos usuarios interactuando cada día a cada hora y además es mantenido por equipos de diseño, Q&A, marketing, backend, frontend y devOps.

Entras al team de frontend e inmediatamente te tienes que chutar la info de la metodología a seguir, como están trabajando los repos porque gitflow, los ambientes que local, staging y producción, que hay que setupear y como para correr el proyecto en local, variables de entorno, agregar API Keys, cuales frameworks o librerías están usando, que convenciones y que estilos para el código se siguen entre muchas cosas mas. Ese frontend soy yo... #EsDeMamador ojo aquí con esa intro!!

Ya en serio ese frontend dev puede ser tu en estos momentos, o tu en un futuro o tal vez ya pasaste por eso varias veces. De lo que voy a hablar ahorita es sobre donde es común encontrar documentación y de que clase. Se me fue de la mano el titulo de documentación perrona, my bad.

Al llegar a un proyecto que ya ha pasado por un montón (chingo) de gente lo primero que hacen es crear tus cuentas, darte accesos y permisos. Usualmente al primer lugar que vas a parar es al repositorio, donde forzosamente (si o si y si no está huye) debe existir un archivo readme.md.

El Readme

Aquí lo que esperamos leer es una explicación paso a paso de como hacer funcionar el proyecto en tu equipo, maquina, ordenador o PC (como le quieras llamar).

Muy probablemente encontraremos:

• Dependencias necesarias a instalar.
• Servicios externos a los que debemos conectarnos por medio de API Keys.
• Donde setear las variables de entorno necesarias.
• Como setear algunos archivos de configuración para conectarnos a otros servicios o plataformas (salesforce o shopify por ejemplo).
• Scripts para hacer build, compilar o correr el proyecto.

Una vez que ya tenemos el proyecto corriendo bien bonito en local, si el proyecto es algo viejo muy probablemente nos veremos frente a frente a una estructura con muchas (un chingo) de carpetas, un sistema de archivos todo raro donde no sabemos ni como empezar o donde están los archivos que necesitamos modificar, también es muy probable que se sigan algún tipo de reglas en el flujo del repo así como algunas  convenciones  eso  lo vamos a checar en la Wiki del repo.

La Wiki

Aquí encontraremos:

• Información sobre la arquitectura del proyecto.
• Sistema de archivos (file system).
• Environments (local, sandbox, staging, production).
• Gitflow (nombre de las ramas, estructura y convenciones de commits, rama principal).
• Convenciones de código.

Vientos ya hay mas claridad pero ahora imagina que nos asignan un ticket de Jira la plataforma usada para la gestión del proyecto y en el cual tenemos que hacer un cambio que se debe ver reflejado en digamos el Product Detail Page (PDP), hay que hacer un cambio en los Reviews pero estamos usando una herramienta externa y hay que hacer cambios en ambas partes: en el code base y en la cuenta de la herramienta para los reviews. Esta ultima normalmente es utilizada por el equipo de Marketing. Es posible que exista un documento en Confluence que explique como usar esa herramienta.

Confluence

Aquí podemos encontrar:

• Documentos o información no necesariamente técnica (ejemplo planeación de Marketing, que nos sirve de referencia para lo que nos toca hacer).
• Información sobre flujos particulares en herramientas externas.
• Howto's sobre como crear o administrar contenido en algún servicio externo.

Una vez que ya sabemos de que va lo que hay que hacer nos pasamos al código, donde muy probablemente algún otro dev se tomó la molestia de dejarnos algunos comentarios sobre partes complicadas en el código.

El código

Aquí podemos encontrar:

• Indicaciones sobre donde comienza un bloque para renderear algún feature en el sistema de plantillas utilizado (desde HTML plano o Liquid, HBS, etc.)
• Indicaciones en una hoja de estilos grande sobre algún feature sobre donde se encuentran ciertos elementos.
• Explicación de soluciones "trickies" o complejas.
• Apuntes raros de porque de ninguna manera hay que remover ciertas líneas de código (100% real no fake, me ha pasado).

Una vez resuelto lo que nos tocaba (bugfix, o feature) es hora de mandar un Pull Request con nuestros commits al repo.

Commits y Pull Request

Dependiendo de las convenciones utilizadas, en el nombre de la rama se puede identificar si se hizo un fix, hotfix, feature, etc. Además cada commit usualmente va acompañado de un subject, body y footer donde podemos agregar la siguiente información:

• Subject: Aqúi vamos a escribir el tipo de cambio que hicimos así como una descripción general.
• Body: Se agrega información mas detallada de los cambios.
• Footer: Aqui se puede agregar el ID o link del ticket del tracker que estamos utilizando (Jira).

En el Pull Request también podemos dejar información, yo acostumbro mandar el titulo y link del ticket del tracker utilizado, además de información extra como screenshots.

Una vez mandado el pull request hay que reportar que fue lo que se realizo y si está listo para probarse ese cambio, esto lo hacemos en los tickets.

El ticket

Es posible que antes de aprobar tu cambio se requiera hacer testing por parte del team de Q&A aquí se van a agregar evidencias como: descripciones, screenshots, videos y una que otra explicación de las implicaciones de ese cambio.

Y después de largas discusiones y cambios retachados por Q&A, una vez que se han cumplido los criterios de aceptación y se ha aprobado el cambio hay que hacer merge de la rama para mandar ese cambio a producción.

Conclusión

No hay que olvidar que cada proyecto es distinto, con diferentes metodologías, distinto workflow, y diversas herramientas. Es más puede que ni si quiera exista esa documentación. Si no existe documentación hay que crearla amigos (ya escribiré sobre eso después, les sigo debiendo el "Como crear documentación perrona").