La importancia de documentar un producto y cómo hacerlo.
Documentar es una inversión, una inversión en escalabilidad, buenas practicas y sobretodo compañerismo.
🇺🇸🇬🇧 First. Do you want to read this article in English? Check it here.
Hay millones de personas trabajando desde sus casas a pesar de todos los problemas que estamos teniendo. Es una situación nueva para muchas de ellas que se ven “obligadas” a trabajar en soledad sin el soporte directo de sus compañeros de trabajo. Y ahí, en esos momentos, es cuando más necesario es documentar procesos y productos para que ese conocimiento (know-how) no se quede únicamente en un empleado y sea compartido.
“No tenemos tiempo para eso ahora mismo. Estamos siempre mejorando el producto, así que documentarlo no tiene mucho sentido.”
Seguramente será lo que oirás al respecto cuando dices “vamos a documentar”, no es una tarea que les guste hacer a todo el mundo y los equipos tienden al caos sino hay procesos y liderazgo claro. Ahí la importancia de PO/PM que ayuden a llevar esa visión.
Documentar nunca es una pérdida de tiempo.
¿Por qué documentar?
El ser humano es el único animal capaz de tropezar dos veces con la misma piedra.
Básicamente para no caer dos veces sobre el mismo error y personas futuras que puedan entrar en la compañía no se encuentren con esos problemas. No se trata de hacerle una foto al proceso o al producto y enmarcarla. La documentación tiene una utilidad palpable, es una tarea dinámica que busca la mejora continua de la empresa. Nos permite conocerla y comprenderla mejor, establecer objetivos y orientar al personal hacia la consecución de estos.
En la formación mediante el ‘boca a boca’ se pierde información relevante que puede afectar a la comprensión del proceso y a su eficacia, además esto implica la transmisión de defectos o maneras de hacer mal las cosas y la persona que está aprendiendo esa nueva tarea, cuando le indiques que eso no es correcto, solo podrá decir “a mi me lo han enseñado así” y esto nos lleva a eso de que “aquí las cosas siempre se han hecho así”.
La documentación permite registrar todos sus pasos, de manera que todas las personas responsables de efectuarlos tengan perfectamente claro qué deben hacer, cuándo hacerlo y cómo.
“El tiempo invertido en documentar es un ahorro de tiempo, ya que cada nueva persona que se incorpore al trabajo solo tendrá que leer y asimilar esa documentación”.
En el mundo de hoy, los usuarios solo quieren que las cosas se hagan. Hay muchas cosas que compiten por su atención: ellos exigen información intuitiva y basada en tareas, debemos de exigir lo mismo para nuestros clientes y nosotros mismos, documentando todo producto y proceso como empresa para nuestros empleados tengan que hacer el menor esfuerzo posible en adaptarse y por tanto en crecer.
¿Cuál es el objetivo?
La documentación consiste en llevar un registro de un proceso durante la ejecución de un proyecto o tarea. El objetivo es aprender de la implementación para adaptar la estrategia y mejorar el procedimiento.
La gestión de procesos de forma proactiva y documentada hará:
- Eliminar errores
- Reducir el tiempo empleado en tareas
- Disminuir los costes de implementación y desarrollo
- Reducir los recursos asociados a las tareas
- Mejorar la eficiencia
- Mejorar la calidad del proyecto
La documentación de procesos ayuda a que otros noten los cambios en el comportamiento y las actitudes necesarias para producir los resultados deseados. También brinda contexto a los procesos, así otros pueden ver cómo el proyecto encaja en el panorama general y cuál es su impacto general.
Ventajas y desventajas de documentar
Obviamente documentar es un coste que debemos de asumir como empresa y como desarrollador y este coste implica una serie de ventajas (a medio-largo plazo) y desventajas (a corto plazo) que debemos de asumir.
✅ Ventajas
La documentación ofrece numerosos beneficios a tu empresa que hacen que el esfuerzo valga la pena.
- Permite cambios oportunos y continuos en los procesos para aumentar la productividad.
- Evita que los procedimientos dejen de usarse por falta de entendimiento.
- Conserva el conocimiento, incluso cuando aquellos involucrados en el proceso se van de la empresa.
- Ayuda a determinar si los procesos son eficientes o si ciertos pasos deben revisarse o eliminarse.
- Ayuda a todos los miembros de una organización a comprender los procesos y a saber a quién contactar en el caso de que haya problemas.
- Mejora la seguridad.
- Sirve como herramientas de aprendizaje que están a mano para nuevos empleados.
- Ofrece contexto a los proyectos individuales.
- Permite la subcontratación ya que puedes transferir conocimiento fácilmente.
❌ Desventajas
Obviamente es un proceso con un impacto en el tiempo del empleado y por tanto tiene un coste económico y puede llevar alguna “desventaja” que simplemente debemos de saber gestionar en tiempo y forma.
- Los implicados puede que se comporten diferente cuando saben que lo que dicen se incluirá en la documentación de procesos.
- La persona que registra un proceso quizás no lo comprenda totalmente.
- Los grupos de interés especial pueden usar la documentación de procesos para generar problemas.
- La documentación hay que mantenerla (sino pierde su utilidad)
- Es posible que en proyectos grandes haya mucha documentación y por tanto lleguemos al punto de necesitar “documentalistas” para mantener toda esa documentación. (Y eso conlleva un coste asociado)
- La documentación puede retrasar un proyecto.
Y precisamente por este ultimo punto debemos de tener en cuenta.
“Hay que buscar el momento ideal para empezar (lo mas doloroso) a documentar y generar ese hábito dentro de la empresa”
Herramientas para documentar
Hay multitud de herramientas con la que podemos documentar y no hay ninguna peor o mejor, eso lo decidirá el equipo. Aquel que se ajuste a las necesidades de trabajo que tengamos y nuestro stack. No obstante tenemos que mirar a largo plazo. ¿Es escalable?. Algunas de estas herramientas son:
- Confluence
- Notion
- Google Docs
- Wordpress
- README (si, un simple readme en un repositorio también es documentación, va por vosotros devs 🙄 )
¿Cómo documentar?
Ahí la gran pregunta que todos los proyectos se enfrentan (a menos que tengan personas con conocimientos de setup de documentación) y lo mas importante a tener en cuenta es que documentar y sus procesos es una democracia al principio y una dictadura al final. Y me explico.
Inicialmente es una democracia porque todo se habla, todo se pacta y por tanto esta abierta a cambios y continuas mejoras, según el proyecto evoluciona y crece (y crece a nivel empleados) sin quererlo estamos “imponiendo” una forma de hacer esa documentación y por tanto los cambios tienen que ser aprobados y cuestan más cambiar la forma de hacer las cosas, por eso digo que es una dictadura.
Si la base de la documentación no es buena, todo lo siguiente no será tan útil como podría ser, por eso es muy importante saber cómo documentar.
No solo necesitas documentar, sino que debes hacerlo de forma adecuada. Un procedimiento mal redactado puede traer problemas. Entre las causas más comunes de malas documentaciones podemos encontrar:
- No explicar el motivo o propósito de la tarea / proceso
- Omitir información relevante
- Incluir información innecesaria y que distrae
Reglas básicas de documentación
Desde mi experiencia hay 9 reglas básicas para una buena documentación estas son:
1- Escribir documentación que sea atractiva y clara
La regla más importante de una buena documentación es que sea lo más atractiva posible. Esto significa que debemos intentar escribirlo en los términos más claros posibles sin omitir ningún paso. Debemos evitar hacer suposiciones sobre lo que nuestros compañeros pueden saber. A veces esto puede parecer exagerado, y podemos estar tentados a decir algo como “todo desarrollador de X sabe de Y”, pero cada uno de nosotros aportamos nuestros propios antecedentes y experiencias a un proyecto.
Aunque esto puede resultar en una documentación más detallada, en última instancia es más simple, ya que hay menos conjeturas para los desarrolladores con todos los niveles de experiencia.
2- Documentación completa, detallando todos los aspectos del proyecto.
La documentación debe ser exhaustiva. Esto significa que todos los aspectos del proyecto están documentados. Las características o excepciones indocumentadas pueden llevar a la frustración y convertirse en una pérdida de tiempo, ya que los usuarios y otros desarrolladores se ven obligados a leer el código para encontrar las respuestas que necesitan. La documentación completa de todas las características elimina este tipo de ambigüedad.
3- Escribir documentación que pueda ser ojeada de forma rápida
Cuando escribimos documentación que es skimmable (ojeable rápidamente), ayudamos a los usuarios a encontrar el contenido que necesitan rápidamente. Para hacer que la documentación sea más fácil de leer, se pueden utilizar encabezados claros, listas con viñetas y enlaces. Para la documentación de grandes proyectos, una tabla de contenidos o una navegación clara ayudará a los usuarios a saltar directamente a lo que necesitan, en lugar de desplazarse por un único documento largo.
4- Ofrecer ejemplos siempre es una buena idea
Documentación que incluye ejemplos que permiten a los developers ver cómo pueden usar el código ellos mismos. El objetivo es proporcionar ejemplos de los casos de uso más comunes para el proyecto, a la vez que se deja que la documentación exhaustiva detalle todas las posibilidades.
5- Escribir documentación que tenga repetición, cuando sea útil
Es perfectamente aceptable incluir alguna repetición en la documentación. Al hacerlo, se reconoce que los usuarios no pueden leer los documentos completos o que alguna información es relevante en varios lugares de la documentación. Mientras que un buen código puede estar SECO, una buena escritura tiene como objetivo ser clara, y a veces esto significa repetirse a sí mismo.
6- Actualizar la documentación
La documentación efectiva se mantiene actualizada. Esto es sorprendentemente desafiante. Podemos comenzar nuestro proyecto con las mejores intenciones y una gran documentación, pero a medida que nuestro software evoluciona y nos estamos poniendo en marcha rápidamente, puede ser fácil caer fuera de ritmo. ¿Cómo podemos conseguir esto? Dedicando tiempo a ello. Al finalizar el sprint hay que documentar lo trabajado.
7- Escribir documentación a la que sea fácil contribuir
La documentación a la que es fácil contribuir también es fácil de mantener actualizada. La forma más sencilla de hacer que la documentación sea fácil de aportar es utilizar software como este mismo. Notion, que nos permite tener bloques de documentación, edición on-live con otros miembros del equipo, y cambios realizados.
8- Escribir documentación que sea fácil de encontrar
La documentación es tan útil como fácil de encontrar. Mantener la documentación actualizada y enlazar con una documentación más extensa cuando sea necesario ayuda a mantener la facilidad de encontrar, detallar y mejorar toda la documentación.
9- Cuatro ojos ven más que dos
En la medida de lo posible (a menos que haya una persona en el equipo que se dedica íntegramente a documentar) es mejor que la documentación pase por una revisión de algún colega de trabajo. Recordemos que no haces la documentación para ti, sino para el resto de compañeros. Un doble-check evita ambigüedades.
Buenas practicas
Documentar puede ser pesado, y tener un coste inicial alto, pero al final la mejor forma o el mejor ejemplo a la hora de plantear una documentación es…
Si entra una persona nueva que me pueda ayudar en mi puesto (ejemplo, Front-end Developer) ¿Qué me cuesta más? Enseñarle toda la forma de trabajo, estructura y planteamiento, o darle una documentación detallada y que solo tenga que resolver dudas.
Por otra parte está el coste de oportunidad y la productividad de una nueva incorporación, sin una documentación, y detalle de todos los procesos de trabajo la persona empieza a ser productiva a los 30–45 días, con documentación puede ser productiva en 10–15 días.
Por ello debemos de tener muy presente además de las reglas de documentación una serie de buenas prácticas (comúnmente llamado… sentido común), 3 cosas muy básicas.
- No hagas la documentación para ti, haz la documentación que te gustaría leer. Plantéalo como el típico repositorio de github para instalar una librería… todo documentado y bien especificado, con sus steps y detalles. ¿A que mola? Pues eso es lo que le mola a todo el mundo :) Haz lo que te gustaría recibir. Y obviamente… eres libre de comentar y pedir más detalle en cualquier documentación que veas incompleta o con falta de detalle.
- Ortografía. Esta claro que puede haber pequeños fallos de ortografía, pero planteemos una documentación con un mínimo de profesionalidad, (no somos niños sin estudios), cosas tan básicas como acentuación, nuevo párrafo empieza en mayúscula, etc…
- Darle color. Aplicar estilo y un poco de mimo gráfico a la documentación, que no te importe añadir imágenes, encabezados, colores o bloques para llamar la atención la / es tu amiga, al escribir / veremos muchos tipos de bloques.
Dicho esto y no menos importante… veamos un rápido ejemplo.
Un ejemplo de documentación
🚫 Qué no hacer
Para instalar la librería simplemente la arrastramos en el proyecto, la configuramos y debería de arrancar con normalidad, a partir de ahí simplemente será necesario en la linea de código que consideremos llamarla mediante callAction(); y nuestro servicio se ejecutará.
Cuidado porque si el entorno no está configurado correctamente es posible que no funcione. Habla con Fran al respecto si tienes algún problema.
✅ Qué sí hacer
Para proceder a tener el servicio activo, necesitaremos descargar la librería correspondiente.
Una vez descargado el .zip deberemos de importarlo a nuestra librería, puedes ver más información sobre como añadir nuevas librerías en “Añadir nuevas librerías al proyecto” (link a otra pagina)
Deberemos de configurar el servicio en nuestro entorno, importante tener en cuenta los servicios de STAGING y PRODUCCION es posible que el servicio no funcione correctamente estando en STAGING por la velocidad de carga.
La configuración por defecto es la siguiente
Una vez tengamos instalado, simplemente debemos de llamar a la función para lanzar el servicio, para llamar a la función procedemos a:
En el caso de que quisiéramos borrar uno de los puntos simplemente lo ejecutaríamos pasando el ID del punto (en este caso, annotation) y con la función correspondiente.
Como veis lleva algo más de trabajo, pero lo que estamos aportando a la empresa es el completo know-how de un proceso un proceso que es posible que tu no vuelvas a hacer, pero la persona nueva que vaya a entrar lo valorará y mucho.
“Documentar es una inversión, una inversión en escalabilidad, buenas practicas y sobretodo compañerismo”.
¿Te ha gustado el post?
¡Dale claps! puedes darle hasta 50 veces al clap, y que mucha más gente encuentre y conozca este post, y claro… no te olvides de compartir.
¡Veamos esos aplausos!
Agradecimientos especiales a mis compañeros y amigos, Pedro Cordero, David Stanete, Ruben Dario, a todo mi squad de Creditas y todos los que me faltan que me han ayudado a completar este artículo. Thanks!
Otros artículos que pueden interesarte…
