Institucional

Empatía, priorización, integración y divulgación: los 4 motores de la jornada de documentación de VTEX.

Beatriz Guerreiro
Beatriz Guerreiro June 8, 2021
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!

Continúe leyendo: historias relacionadas
Institucional

VTEX Grand Prix Colombia 2023: Reconociendo la innovación y el éxito en el Comercio Digital

El VTEX Grand Prix sobresale anualmente como uno de los eventos más destacados en el ámbito del digital…

Andres Prieto
Andres Prieto
Institucional

¡VTEX Grand Prix Ecuador 2023: Celebrando la excelencia en Comercio Digital!

El VTEX Grand Prix es nuestro evento anual de comercio digital, celebrado en varios países de Latinoamérica, como…

Andres Prieto
Andres Prieto
Institucional

VTEX obtiene medallas en todas las 24 categorías del Paradigm B2B Combine: Enterprise and Midmarket Editions 2023

La empresa de análisis de ecommerce, Paradigm B2B, publicó su informe anual B2B Combine, en el que califica…

Lalo Aguilar
Lalo Aguilar
Institucional

VTEX lanza nuevos productos que optimizan las inversiones en comercio digital

VTEX Day 2023, un evento de dos jornadas al que asistieron más de 20 000 personas por día fue…

Lalo Aguilar
Lalo Aguilar
Institucional

VTEX Grand Prix Colombia 2022: ¡Conoce a todos los ganadores!

VTEX Grand Prix es el evento de premiación más importante del ecommerce en la región. Este acontecimiento es…

Andres Prieto
Andres Prieto
Institucional

Cuadrante Partners VTEX LATAM 2022

El Cuadrante de Partners VTEX LATAM 2022 ha sido creado para reconocer el desempeño de nuestro ecosistema de…

Cristina Cortes
Cristina Cortes
Institucional

VTEX es nombrada ‘Visionaria’ en el 2022 Gartner® Magic Quadrant™ for Digital Commerce

VTEX ha sido nombrada Visionaria por tercer año consecutivo en el 2022 Gartner® Magic Quadrant™ for Digital Commerce,…

Caley Iandiorio
Caley Iandiorio
Institucional

VTEX es ahora un partner oficialmente certificado por Mercado Libre en Chile, Colombia, Perú y Argentina

Los que están al día de las novedades de VTEX ya se habrán enterado de que nuestra integración…

Juliana Sales
Juliana Sales
See More