DEV Community

Cover image for Documentar sí, pero que sirva para su propósito
Núria Isart for Adevinta Spain

Posted on • Updated on

Documentar sí, pero que sirva para su propósito

Escrito por @the_turo y Núria Isart

.

Este post no pretende ser una guía sobre cómo hacer una buena documentación, ya hay miles de posts de este tipo en la red y no queremos repetir lo mismo una y otra vez. Lo que queremos es plasmar nuestra experiencia en relación a la documentación: en qué situaciones nos hemos encontrado y cómo considerando estos escenarios hemos adaptado la documentación para ayudar al entendimiento del equipo y el avance del proyecto.

Muchas personas ven la documentación como una parte del proceso tediosa, repetitiva y cansada; aunque es de las partes más importantes del proyecto. Una buena documentación agilizará el buen funcionamiento y desarrollo del equipo o será un stopper que impedirá la alineación e incluso detendrá el desarrollo.

En primer lugar, hay que tener en cuenta el quién: ¿para quién va dirigida la documentación? Conocer qué es lo que le preocupa y necesita encontrar el usuario, o en nuestro caso el equipo, de esa documentación determinará el contenido.

Partiendo de la base de que la documentación es para todos los perfiles nos encontramos diferentes escenarios que hemos vivido y profundizaremos en el que más nos hemos encontrado como equipo:

  • Escenario 1: A pesar de invertir esfuerzo en documentación, el equipo no se entiende.
  • Escenario 2: La comunicación fluye y el equipo se entiende desde un inicio.
  • Escenario 3: La comunicación no es tan fluida, pero con la documentación se trabaja para llegar a entenderse.

Escenario 1

A pesar de invertir esfuerzo en documentación, el equipo no se entiende.
Este es lamentablemente un escenario muy común. El equipo de diseño invierte mucho tiempo creando especificaciones y sin embargo la comunicación no fluye, no se consultan esos documentos y aunque lo desarrollado tenga buena calidad, no guarda relación con lo diseñado inicialmente.
Alt Text

En nuestra experiencia esto se puede deber a uno o más de estos fallos:

  1. Falta de naturalidad: La comunicación en el equipo es forzada. Esto puede ser porque los miembros vayan a velocidades diferentes, porque no comprendan los tecnicismos de la otra parte, o quizás simplemente porque a pesar de referirse a lo mismo no hablan el mismo lenguaje (por ejemplo lo especificado como “color-red-light” se llame “error-L1” en código).
  2. Falta de transparencia: En equipos multidisciplinares, donde los diferentes miembros trabajan paralelamente en diferentes tareas, cada uno lo hace en un silo y la visibilidad del trabajo del otro es muy pobre, se dificulta la alineación, la retroalimentación y en definitiva se promueven malas prácticas cómo hacer sesiones de alineación después de haber entregado.
  3. Visión de túnel: El enfoque es incorrecto si la tarea se resume en entregar diseños a desarrollo. Este foco excesivo en “crear especificaciones” es muy común en un modelo de trabajo en cascada en el cual se diseña, luego se especifica, luego se desarrolla, etc., y que tiene una serie de desventajas que quedarán más claras por contraste en los siguientes escenarios.

Escenario 2

La comunicación fluye y el equipo se entiende desde un inicio.
Facilitar el entendimiento en el equipo es el mayor objetivo de una buena documentación pero no es suficiente ni viable a largo plazo si requiere de mucho esfuerzo.
Alt Text

Idealmente un diseñador no debería invertir casi tiempo creando especificaciones es por eso que el escenario perfecto es aquel en el cual los miembros del equipo se conocen y se entienden sin necesidad de grandes esfuerzos o documentos y mucho mejor si lo hacen de manera natural desde el inicio del proyecto.

Independientemente de los puntos básicos que todo handoff debe incluir (espaciados, colores, tipografías, escenarios, prototipos, tracking, copy, links relevantes, etc.) una comunicación sin esfuerzo sienta bases en tres pilares compartidos por todo el equipo:

  1. Naturalidad: Todos hablan el mismo lenguaje de producto, están en la misma página, hablan de lo mismo cuando es relevante y comunican si no entienden algo.
  2. Transparencia: Todos conocen el estado actual de lo que están haciendo, saben cómo revisarlo, cómo dar feedback y cómo resolver conflictos en caso de desacuerdo.
  3. Visión 360º: Gestionan bien no solo la entrega sino todo lo que viene antes, durante y después. Las especificaciones no se crean al terminar el diseño sino que forman parte del diseño, todos los miembros del equipo tienen acceso a los diferentes archivos y documentos del proyecto desde el principio y conversan sobre lo que se espera del trabajo mucho antes de comenzar a desarrollar, inclusive en fases tempranas de investigación e ideación, y si algo se deja fuera del output final se documenta y almacena de manera clara y accionable para poder recuperarlo después.

Escenario 3

La comunicación no es tan fluida, pero con la documentación se trabaja para llegar a entenderse.
Este es un caso bastante común sobretodo en equipos de nueva creación y es el que usaremos para explicaros nuestra experiencia. Nos encontramos frente a un equipo donde hay un cierto distanciamiento entre la definición de la funcionalidad y el desarrollo de esta.
Alt Text

Esta fricción causa que la funcionalidad se desarrolle sin tener en cuenta la definición o considerándola parcialmente y, por tanto, esta difiere de lo estipulado de inicio. Para corregir esta situación y crear puentes entre todos los miembros del equipo la documentación es clave.

En este escenario todos los miembros del equipo deben realizar un gran trabajo de empatía y entendimiento donde tienen que esforzarse para entenderse.

Si nos centramos en los tres pilares comentados, podemos ver que en este escenario se debe realizar un esfuerzo para el entendimiento del equipo trabajando conjuntamente en la definición de la funcionalidad y forzando esos momentos de diálogo para poder llegar a un escenario de fluidez.

  1. Trabajar la naturalidad: Es crucial entender las diferenciaciones en el lenguaje para poder llegar a entenderse a pesar de hablar en distintos términos. Aquí es muy recomendable disponer de un glosario del equipo con las definiciones de los distintos términos que entran en conflicto. Al verbalizar su significado se llega a la conclusión que había otros términos sinónimos para referirse a la misma palabra o tenía matices diferentes. Este ejercicio de glosario conjunto permitirá una mejor comprensión y será la base para llegar a usar el mismo lenguaje.
  2. Visibilizar el trabajo para generar transparencia: Las funciones no pueden ir por libre centrándose cada una en su nicho, deben ser conscientes de qué se está trabajando en todas las áreas del equipo aunque no participen activamente y deben tener visibilidad de las distintas acciones y documentos.
  3. Construir conjuntamente la visión 360º: Los equipos que se encuentran en este escenario es muy recomendable que realicen mucho trabajo conjunto de definición no solo pensando en el corto plazo, sino también en el medio-largo plazo. El incluir a todas las áreas en los diferentes momentos de ideación y creación hará que interioricen mucho más la solución, se la hagan suya e incluso puede que esto modifique el enfoque de la documentación.

Un ejemplo práctico

Al inicio de trabajar con el equipo nos encontramos en esta situación. Todos queríamos entregar muy rápido valor y, por esa necesidad de entrega inmediata, no se validaba bien que la funcionalidad entregada fuera la documentada.

Otro punto que se sumó a la rapidez, fue la falta de visibilidad. Cada función hacía su parte, había menos transparencia y, por tanto, esto condujo a que ciertas funcionalidades se tuvieran que definir de nuevo o ajustar la documentación.

Aquí hubo un gran trabajo de coordinación con reuniones previas de explicación de las funcionalidades previo a la documentación y reuniones post de validación. Después de varias semanas con la misma dinámica, empezamos a trabajar mucho mejor en equipo y cada vez eran menos necesarias las validaciones posteriores o debatir el significado de los términos porque todos ya sabíamos a qué nos referíamos y cuáles eran los estándares de calidad de entrega.


Documentamos para entendernos

Con este ejemplo, queremos recalcar que no siempre los equipos empiezan trabajando en el escenario 2 que se supone que es el ideal donde todos se entienden a la perfección. En muchos casos, y sobretodo equipos de nueva creación donde los miembros no han trabajado previamente juntos, se debe realizar un trabajo previo de alineación para que todo el equipo tenga claro cómo trabaja el resto, y vaya más coordinado en entender las funcionalidades a desarrollar y los estándares de calidad exigidos de cada funcionalidad entregada.

Documentamos para que el equipo llegue a acuerdos y se realice el producto de forma más ágil, pero también documentamos para dejar constancia de lo que se ha hecho y si en un supuesto hay un cambio de equipo o entran nuevos miembros, estos puedan realizar un onboarding con facilidad sumergiéndose en lo escrito para ponerse al día de forma más rápida y eficaz.

Documentar sí, pero no hace falta documentarlo todo. Debemos hacer documentación que sirva, y en función de en qué escenario nos encontremos deberemos detallar más las funcionalidades o menos. Al final, documentamos para entendernos.

Alt Text

Top comments (0)