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!
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". Por supuesto esto no otorga mucha evidencia acerca de la definición así que comencé a buscar "¿Cómo documentar un proyecto de software?" en Google.
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 (ノ°▽°)ノ︵┻━┻
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.
Pero si estas cuatro son excusas ciertas y totalmente válidas, ¿por qué estoy tratando de convencerte de que es importante 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.
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?
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.
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.
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:
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.
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.
Me gustaría mencionarte algunos otros consejos que me parecen importantes para que apliques a tu documentación.
Recordá siempre intentar agregar valor a todo lo que hagas como dev en el lugar en donde trabajes.
¡Muchos éxitos!