Documentación de Snyk: nuestro recorrido hasta ahora

Como responsable de la documentación para usuarios de Snyk durante los últimos tres años, he supervisado muchas mejoras en nuestra documentación para usuarios.

Una cultura de colaboración

Hemos creado una cultura de colaboración única para nuestra documentación para usuarios. Cientos de colaboradores activos de Snyk crean, actualizan y mejoran el contenido continuamente.

Una de las principales formas en que lo hemos logrado es adoptando un proceso de documentación como código en nuestro equipo de documentación.

Documentación como código

En pocas palabras, un proceso de «documentación como código» significa que el proceso de redacción refleja el proceso de desarrollo de código y, por lo general, adopta plataformas y herramientas fáciles de usar para los desarrolladores. Por ejemplo, la documentación de Snyk usa la plataforma GitBook, que emplea un conjunto de procesos similares a Git para gestionar los cambios, tiene una interfaz de edición sencilla y se sincroniza con un repositorio de GitHub para el contenido almacenado en archivos markdown.

Este proceso ha facilitado plenamente las contribuciones. Al eliminar la pronunciada curva de aprendizaje y las restricciones de acceso asociadas a las herramientas profesionales de creación de contenido, más personas pueden trabajar en el contenido sin afrontar costos de licencia prohibitivos.

Cómo crea Snyk su documentación

En Snyk, nuestros equipos de desarrollo redactan el primer borrador de la documentación de cada función nueva en el entorno de escritura de GitBook. Esto les da sentido de pertenencia y fomenta su participación, lo que les permite contribuir rápidamente al contenido sin tener que migrarlo manualmente ni volver a darle formato desde otras fuentes. Al iniciar el desarrollo de la documentación antes de que las funciones pasen a las pruebas, a menudo está lista y publicada cuando la función entra en la fase de beta cerrada, para que nuestros usuarios accedan a la información de forma rápida y sencilla.

Capacitamos, apoyamos y motivamos a todos nuestros colaboradores; les brindamos asistencia mientras editan (con la herramienta Grammarly) y nos aseguramos de que todas las revisiones y los cambios sigan un estándar. Cada nuevo integrante de los equipos de I+D recibe orientación específica y se le asignan escritores para que sepa cómo contribuir y pedir ayuda. La asistencia temprana y la automatización son fundamentales para garantizar que la documentación pueda escalar adecuadamente; por eso, hacemos hincapié en ellas en el enfoque de Snyk.

En pocas palabras, Snyk sigue dos enfoques:

• Shift-left: prueba tu código antes, mientras lo escribes, no solo antes de lanzarlo.

• Shift-down: haz que los desarrolladores realicen las pruebas, en lugar de equipos especializados en seguridad.

Nuestros procesos de documentación siguen este mismo modelo. La colaboración, la capacidad de escalar y la automatización forman parte de nuestro ADN cultural.

Logros de nuestra cultura de colaboración

Al transformar la forma en que Snyk crea documentación, a principios de 2024 ya teníamos más de 250 colaboradores activos. Además, en los últimos dos años hicimos más de 6,000 cambios y mejoras en nuestra documentación: casi 10 al día.

El personal participa y se involucra, y los escritores técnicos son vistos, como corresponde, como facilitadores de funciones, no como obstáculos. Hemos evitado las prisas de último minuto para documentar una función, que pueden retrasar el lanzamiento, dar lugar a documentación de mala calidad o ambas cosas.

En qué estamos trabajando: experiencias, tipos y opiniones de los usuarios

Ahora nos enfocamos en mejorar la calidad de nuestra documentación, adaptarla a las experiencias y los perfiles de los usuarios de Snyk, y ofrecer contenido más prescriptivo y con recomendaciones claras.

Adaptación a las experiencias de los usuarios

Actualmente estamos transformando la arquitectura de información de nuestra documentación. Siempre hemos ofrecido documentación «descriptiva» clara para explicar a los usuarios cómo usar los productos de Snyk. Sin embargo, contamos con poca documentación «prescriptiva» que recomiende buenas prácticas o proporcione ejemplos detallados. Sin esa orientación, los usuarios tenían que definir sus propias rutas de implementación, porque la estructura de la documentación no se ajustaba a sus experiencias, recorridos ni perfiles.

Dónde empezamos

Esta es nuestra estructura de 2022, centrada en los productos de Snyk:

Describir el recorrido

Ahora contamos con una arquitectura de información simplificada y específica que se adapta a la experiencia lineal del usuario:

Nuestro recorrido de contenido incluye:

• Secciones iniciales que describen la primera parte de la experiencia del usuario («incorporación»), incluido un Inicio rápido para evaluar las funciones y una sección Implementar Snyk para planificar a un nivel más general la implementación en tu negocio.

• Después, describimos los detalles de las integraciones con Snyk, incluidas las integraciones de Git para vincular inicialmente tus repositorios de administración de código fuente con Snyk, y las integraciones de CI/CD para estrategias de implementación a largo plazo.

• Luego abordamos las operaciones cotidianas de Analizar con Snyk, incluido el uso de cada producto de Snyk, como Snyk Open Source

• También incluimos tareas generales de administración en la sección Administración de Snyk.

• Terminamos con descripciones de dos áreas independientes: CLI y API

Adaptación a los perfiles de usuario

Hemos identificado varios perfiles de usuarios de Snyk que consultan nuestra documentación con frecuencia: desarrolladores, administradores e implementadores, y personal de seguridad de aplicaciones.

Cada perfil de usuario tiene necesidades de información distintas. Por eso, queremos que nuestra documentación sea fácil de consultar y navegar para todos estos perfiles, y que permita acceder a las áreas de contenido más relevantes para cada uno.

Por ejemplo:

• Desarrolladores: ofrecemos contenido de Inicio rápido y Analizar con Snyk

• Administradores e implementadores: pueden enfocarse en la Configuración empresarial y la Administración de Snyk

• Seguridad de aplicaciones: se enfoca en Administrar el riesgo

Ofrecer recomendaciones más claras

A lo largo de los años, hemos desarrollado un amplio conocimiento sobre cómo ayudar a los clientes a implementar Snyk con éxito, desde la incorporación hasta el uso cotidiano. Este contenido con recomendaciones claras incluye casos de uso detallados, guías paso a paso, recomendaciones y otros materiales prescriptivos. Estamos reuniendo y publicando todo este conocimiento.

Este contenido ayudará a todos los usuarios a planificar cada etapa de su experiencia con Snyk. Además, sabemos que nuestro creciente mercado empresarial necesita más contenido de este tipo, con materiales de capacitación accesibles y escalables que les permitan ejecutar un programa eficiente de incorporación a Snyk en sus propias organizaciones.

Empezamos a crear este contenido con las guías de implementación de Snyk en la sección Implementar Snyk.

Próximos pasos

Nuestro recorrido con la documentación está lejos de terminar.

Estamos poniendo en marcha y planificando muchos proyectos interesantes de documentación para 2024, entre ellos:

• Agregar elementos narrativos coherentes en toda la documentación para que nuestros clientes los usen como plantillas.

• Incorporar IA útil en la experiencia del usuario para responder rápidamente a tus preguntas.

• Integrar el contenido más cerca de la experiencia del usuario para que accedas a la ayuda de forma más rápida e inteligente.

• Agregar un registro de cambios detallado y coherente que abarque todos los cambios funcionales de Snyk.

• Mejorar y publicar un catálogo completo de mensajes de error.

¡Así que no pierdas de vista la documentación para conocer más detalles!