Empatía, priorización, integración y divulgación: los 4 motores de la jornada de documentación de VTEX.
A pesar de que hoy en día muchas empresas de tecnología reconocen la importancia de una buena documentación para el éxito de sus productos digitales, aún observamos mucha inercia en este ámbito en el mercado.
Sin duda alguna, en la práctica, todas las empresas desean los resultados concretos que proporciona una documentación técnica de calidad. Pero ¿están preparadas para invertir esfuerzos y reconocer que esta jornada requiere, ante todo, compromiso?
Con un equipo limitado de tech writers y un largo historial de productos desarrollados sin la documentación adecuada, nuestro equipo en VTEX sintió los dolores del crecimiento acelerado sin el soporte adecuado para la escalabilidad del conocimiento. Por lo tanto, aprendimos por experiencia propia que el desafío de producir una documentación técnica es tan grande como su importancia para el futuro de la empresa.
¡Nuestra jornada hasta aquí ha sido ardua, pero muy gratificante! A partir de ella, compartimos algunos insights que fueron fundamentales para la estructuración de nuestra documentación, agrupados en cuatro pilares importantes: empatía, priorización, integración y divulgación.
Empatía para escribir documentación funcional
El arte de la comunicación se basa en la capacidad de transmitir mensajes de un emisor a un receptor, sin ruidos eventuales que dificulten el intercambio de información. Si, como emisor, no entiendes el mensaje que quiere transmitir y el receptor que lo va a recibir, ¿cómo esperas tener éxito en su comunicación?
Sin el conocimiento adecuado del producto y de sus usuarios, es poco probable que una empresa tecnológica supere el obstáculo de la documentación en su trayectoria de crecimiento.
Aunque suene un cliché, la empatía es un factor fundamental que a menudo se pasa por alto en la jornada de documentación. ¡Con VTEX no fue diferente! Muchas veces publicamos documentación sin obtener los resultados deseados, precisamente porque la redactamos sin la debida empatía con nuestros clientes.
Aprendimos la lección: una persona solo puede producir documentación funcional cuando realmente es empática para entender todos los casos de uso del producto, más allá de un único punto de vista. La empatía es una práctica diaria que nos ayuda a comprender el producto y los usuarios a profundidad, así como a identificar las tareas que deben ser priorizadas a partir del impacto que tendrán en el desarrollo de la empresa.
Priorización para generar impacto
Cuando damos el primer paso en una larga jornada, es habitual que pensemos más en el destino final de que en el punto de partida.
Siguiendo esta lógica, depositamos grandes expectativas en la rápida entrega de valor a los usuarios, a menudo ignorando el esfuerzo necesario que exige la construcción y ejecución de un backlog que sea realmente relevante para los lectores de la futura documentación.
Un error común de VTEX fue tratar de planificar un backlog que contemplara el amplío desafío que teníamos por delante. Sin mucha sorpresa, terminamos entregando poco impacto y perdiéndonos en medio de tantas tareas por ejecutar.
No te equivoques: un backlog extenso no necesariamente representa las principales lagunas de documentación de un producto. Usualmente, solo es el resultado de las múltiples demandas (con diferentes niveles de urgencia) que surgen de todas las áreas en esta primera etapa de la jornada.
No aceptar pasivamente todas las demandas de documentación fue uno de los cambios más importantes para nuestro equipo. A partir de eso, entendimos por nuestra cuenta dónde residían las mayores oportunidades de impacto, identificamos qué tareas las reflejaban realmente y, finalmente, utilizamos la documentación como herramienta para generar resultados concretos en la producción de conocimiento de la empresa.
Integración para escalar esfuerzos
¡Si solo te preocupas por llenar lagunas, lo más probable es que nunca dejen de existir! Yo diría que esa es la principal lección que hemos aprendido.
El producto se reinventa a diario y, por eso, recibimos nuevas demandas constantemente: entonces ¿cómo podemos acompañar el ritmo acelerado de la documentación? Con un equipo limitado de tech writers y un gran desafío por delante, apostamos por procesos bien integrados con el equipo de desarrollo para escalar esfuerzos, que se reflejan en:
- Iniciativas colaborativas de documentación, como docathons, —maratones de grupos de trabajo en los que los desarrolladores comprometidos con la documentación se reúnen para actualizar la documentación antigua o crearla desde cero—.
- Flujos de trabajo que confluyen entre tech writers y desarrolladores, garantizando que las nuevas funcionalidades y actualizaciones estén siempre identificadas y documentadas antes del despliegue.
- Estandarización de la nueva documentación en plantillas, como este README que adoptamos como punto de partida para las aplicaciones de React de VTEX. El uso de una buena plantilla de documentación respalda el proceso independiente de escritura de los desarrolladores durante el flujo de trabajo y, en consecuencia, la posterior revisión por parte de los technical writers.
Invertir en la integración con el equipo de desarrollo y en que este útlimo comprenda la importancia de la documentación acelera los resultados e intensifica sus impactos. En los últimos dos años, encaramos una verdadera revolución en la documentación de VTEX, principalmente a partir de la inclusión de los tech writers en el día a día del equipo de desarrollo y en el compromiso de este último con la resignificación de la cultura de documentación y el Definition of Done del producto. Lo que antes se descuidaba se convirtió en una regla clara: sin documentación, no hay despliegue.
Divulgación para garantizar consistencia
¿Cómo las personas deben buscar apoyo en la documentación cuya existencia aún no conocen?
En el afán de aportar valor a los usuarios del producto, solo nos preocupaba la cantidad de documentación escrita y dejábamos de lado comunicar lo que ya se publicó, es decir, lo que ya está disponible para realizar consultas.
Durante muchos años, el equipo de VTEX siguió produciendo nueva documentación, pero sin reflexionar sobre su divulgación necesaria. El resultado, que hoy es comprensible, fue amargo para nosotros en su momento: pocos accesos en contenidos que nos exigían grandes esfuerzos.
A partir de este error hemos aprendido la siguiente lección: la divulgación de nueva documentación o, incluso, de actualizaciones importantes de la antigua, genera:
- Transparencia en el trabajo de los tech writers.
- Accesos en la documentación ya publicada.
- Feedbacks valiosos de los usuarios para mejorar la documentación.
A partir de eso, apostamos por formatos claros de comunicación, como las release notes, y por canales de interacción amplios, como Slack. No pasó mucho tiempo antes de que cosecháramos los fértiles resultados que mencionamos anteriormente, debido al consumo real de nuestra documentación por parte de nuestros clientes.
Independientemente del formato y del canal elegido, lo más importante es no caer en el error común de publicar sin continuar la divulgación posteriormente. Recuerda: la nueva documentación funciona esencialmente como un nuevo producto digital de la empresa —si nadie la conoce, nadie la utiliza—.
Abraza la jornada infinita de documentar
En cualquier nuevo camino de la vida, el primer paso es siempre el más desafiante. La inseguridad de no poder avanzar persiste hasta que realmente nos equilibramos sobre nuestros pies y nos arriesgamos a realizar el primer movimiento.
Como era de esperar, VTEX se arriesgó. Nos comprometimos a cambiar nuestro paradigma de documentación e invertimos mucho en el cambio siguiendo nuestros principios: «Trust to be trusted», «Build for community», y «Be bold». Actualmente, satisfechos con cada paso dado hasta el momento, compartimos los principales aprendizajes de nuestra jornada que aún está en curso.
Aún está en curso porque no tiene fin. La meta de este maratón es en realidad una ilusión: cuanto más escribas, más lejos llegarás. ¡Y está bien!
Los productos digitales evolucionan constantemente y, por tanto, también lo hace su respectiva documentación. La única certeza es el cambio, el esfuerzo es continuo. Haz las paces con la imprevisibilidad y celébrala —¡la infinidad de la jornada de documentación no es más que el reflejo directo del crecimiento acelerado de una empresa!—.
El Tech Writer es el responsable de toda la documentación técnica de los productos digitales de una empresa. ¿Estás interesado en esta carrera? Accede aquí a todas las oportunidades disponibles de VTEX y únete a nuestro equipo!
