En la industria high-tech, la documentación técnica suele verse como un extra. Te contamos cómo aprovecharla para aportar valor real al producto.
Cómo convertir la documentación técnica en un activo valioso
Llevo más de dos décadas como redactora técnica y todavía me sorprende la distancia que hay entre el potencial y la realidad de la documentación técnica.
En los últimos años he venido pensando en cómo, en la industria high-tech, la documentación técnica puede aportar valor real al producto en lugar de ser un mero apéndice.
Tras experimentar con algunos productos, los resultados me convencieron de que vale la pena seguir por ese camino. Desde entonces, he buscado oportunidades para poner a prueba la idea. Ahora, después de seis meses como redactora técnica en DoiT, voy a compartir algunas lecciones aprendidas y reflexiones nuevas.
Lo primero es lo primero
Los redactores técnicos casi siempre se suman al equipo de Engineering o de producto en una etapa más tardía (según cómo cada organización entienda el desarrollo de producto). Al fin y al cabo, hoy en día todos somos escritores y editores. Cuando todavía estás buscando a los primeros adoptantes, los repositorios de GitHub, los blog posts y las discusiones en foros suelen ser más rentables para llegar a tu público objetivo.
Solo cuando el producto ha superado esa etapa inicial y está listo para escalar, alguien suele plantear sumar redactores técnicos. Por mi experiencia, lo primero que esos redactores técnicos deben hacer es sentar las reglas básicas mediante convenciones.
Puede sonar raro poner las convenciones en primer lugar al hablar de una industria que presume de innovación y creatividad. Pero las convenciones no son enemigas ni de la innovación ni de la creatividad. Seguirlas en lo no crítico reduce la carga cognitiva y ayuda a la gente a concentrarse en las tareas que sí lo son.
Las convenciones en la documentación técnica adoptan distintas formas, por ejemplo, una guía de estilo completa ( Google developer documentation style guide, Microsoft writing style guide) o un conjunto sencillo de reglas ( AWS document conventions).
No hace falta una guía de estilo perfecta antes de ponerte a documentar. Lo más eficaz es construirla mientras te familiarizas con el producto. Es decir, hazlo durante tu onboarding.
Estos son los pasos a seguir en esta fase:
- Sienta los fundamentos al hacer la limpieza básica:
- ¿Los encabezados y títulos usan sentence case o title case?, ¿usan gerundio (verbo en -ing) o el verbo en su forma base?
- ¿Los procedimientos se escriben como listas numeradas o como una narrativa larga?
- ¿Hay una regla estricta sobre la coma serial (un buen tema si quieres iniciar un debate entre redactores)?
- ¿Cómo se describen las interacciones de UI? Por ejemplo, ¿el usuario "hace clic", "selecciona" o "elige" un botón?
- ¿Cómo se toman y se presentan las capturas de pantalla? ¿Y los call-outs?
- Construye tu guía de estilo interna sobre la marcha:
- Toma lo mejor de los estándares de la industria y adáptalo a tus necesidades.
- Ten claro que es un documento vivo, abierto a nuevos usos y a terminología nueva.
Una guía de estilo interna es una pieza fundamental de la documentación técnica. No solo te ayuda a escalar tu equipo de redactores, sino que también orienta a otras personas de la organización que necesiten redactar información técnica, ya sea un borrador para los redactores técnicos o un blog post.
En el camino también pueden aparecer temas de mayor calado, por ejemplo:
- ¿Qué tan conversacional o personal es el estilo general?
- ¿Cómo se usan los videos?
- ¿Cómo se maneja la información sensible?
- ¿Quiénes son los stakeholders o colaboradores activos de la documentación técnica?
No te sorprendas con lo que descubras.
El diseño de la documentación técnica
Los productos tecnológicos son complejos. No solo usan tecnologías complicadas, sino que además interactúan con otros productos tecnológicos, muchas veces de otras organizaciones.
¿Cómo enfrentar esa complejidad al escribir documentación técnica?
Una respuesta habitual empieza con: "Depende". Aun así, contamos con dos herramientas potentes: el framework y el modelo conceptual.
Framework
Un framework en documentación técnica puede ser una plantilla o estructura conceptual que facilita escribir temas individuales (es decir, temas que no se relacionan con otros).
La mayoría de los blog posts y de las páginas únicas de documentación técnica se centran en temas individuales y, por lo tanto, se benefician de una plantilla o framework bien definidos.
¿Vas a escribir una guía de instalación?
Piensa en una estructura de tres partes: requisitos previos (incluidos los requisitos de hardware y software), ejecución (los pasos concretos para instalar lo que corresponda) y verificación (revisar la versión, ejecutar un ejemplo hello-world, etc.).
¿Estás armando instrucciones para consultar datos?
Asegúrate de incluir los permisos necesarios, consultas de ejemplo y una explicación detallada de la entrada y la salida.
Aunque no haya una plantilla disponible, con algo de práctica se puede desarrollar un framework con relativa facilidad. Antes de unirme a DoiT, escribí un blog post titulado How to write (and rewrite). El enfoque que se sugiere allí tiene que ver, sobre todo, con la construcción de un framework.
Estos son los puntos clave:
- Usa el Minto Pyramid Principle® para sacar a la luz la estructura de fondo de un texto complejo
- Crea jerarquías visuales que ayuden a la audiencia a moverse en lo complejo
- Diseña categorías que acompañen el recorrido del usuario
Modelo conceptual
La complejidad de los productos tecnológicos se debe en buena medida a las interacciones, ya sea entre componentes de un mismo producto o entre productos de un mismo entorno de negocio o tecnología que deben funcionar juntos para conformar una solución completa.
Por lo general, no expones la complejidad inherente al producto. Tu fórmula secreta puede resultar interesante para tus competidores, pero no necesariamente para tus clientes.
Sí necesitas prestar mucha atención a las complejidades que pueden generar fricción externa. Suelen ser las culpables de bloquear a tus clientes e incluso a tu propio equipo de soporte.
En su aclamado libro The Design of Everyday Things, Donald Norman explica que ofrecer un buen modelo conceptual es el principio más importante para domar la complejidad. Coincido por completo.
Veamos más de cerca cómo aprovechar el modelo conceptual en la documentación técnica, con dos ejemplos del DoiT Help Center.
Funcionalidades tipo bloque de construcción
Al hablar de la funcionalidad Attributions, a Matan Bordo, product marketing manager de DoiT, le gusta decir que es "una de las funcionalidades más adictivas de DoiT Cloud Intelligence™ cuando se usa correctamente". Si concluyes que no es fácil sacarle todo el provecho, te entendemos.
Attributions es una funcionalidad tipo bloque de construcción. Como muchos otros bloques, por sí sola hace poco. Pero cuando captas su esencia, trabajar con ella se vuelve hasta divertido.
En una actualización reciente, revisamos la documentación de la funcionalidad y pusimos los escenarios al inicio, para que los usuarios entiendan de qué es capaz antes de meterse en todos los detalles de configuración.
Funcionalidades de plugin del ecosistema
En septiembre añadimos un artículo llamado Visualize with Grafana Cloud (aportado por nuestro CTO y cofundador Vadim Solovey). Como sabrás, Grafana no es una solución de DoiT, sino un servicio popular dentro del Cloud Native Landscape.
Al igual que en el ejemplo anterior de la funcionalidad tipo bloque de construcción, en la Introducción explicamos la razón de ser de la integración y en qué aspecto puede beneficiar a un negocio que opera en la nube.
Tanto en el producto como en el ecosistema, un buen modelo conceptual describe la relación entre los componentes que interactúan y, así, ayuda a los usuarios a moverse en el dominio que elijan.
¿Otros beneficios? Si hay algo seguro en tecnología es que los usuarios se vuelven creativos cuando la utilizan para resolver sus problemas. Con un modelo conceptual adecuado, descubrirán nuevos casos de uso para tu producto y, mejor aún, se convertirán en evangelistas espontáneos que te ayudarán a seguir mejorando.
Es trabajo en equipo
Entonces, ¿en qué punto estamos?
Las convenciones y los frameworks se pueden abordar con conocimientos genéricos de redacción técnica (por eso son un buen punto de partida para nuevas incorporaciones o redactores junior), mientras que construir modelos conceptuales adecuados en distintos niveles exige un conocimiento profundo del producto.
DoiT es una empresa tecnológica que se enorgullece de su profundo expertise en la nube y de su mentalidad centrada en el cliente. El entorno de aprendizaje es excepcional. Los temas que se discuten en los canales internos de Slack y se comparten en el wiki interno o en StackOverflow están llenos de conocimiento, y la gente tiene muchas ganas de compartir lo que sabe, apoyarse mutuamente y colaborar para mejorar, tanto a nivel individual como colectivo.
Como parte del equipo multidisciplinario de product management, los redactores técnicos son socios de pensamiento de los product managers y diseñadores. Escribir con claridad se apoya en pensar con claridad, algo de gran valor a la hora de sacar a la luz supuestos y modelar funcionalidades del producto.
Al hablar sobre lo que el equipo de redacción técnica quiere lograr, definimos como visión convertir la documentación técnica en un activo valioso dentro de los portfolios de productos de DoiT. La clave está en el trabajo en equipo. Una documentación técnica de calidad no es una tarea solitaria de los redactores técnicos, sino un esfuerzo que el equipo de redacción técnica de DoiT lidera y entrega de la mano de toda la organización.