Documentation Snyk : notre parcours jusqu’ici

Depuis trois ans, en tant que responsable de la documentation utilisateur de Snyk, j’ai supervisé de nombreuses améliorations de notre documentation.

Une culture de la contribution

Nous avons instauré une culture de contribution unique pour notre documentation. Des centaines de contributeurs actifs chez Snyk créent, mettent à jour et améliorent continuellement le contenu.

L’un des principaux leviers a été l’adoption d’un processus docs-as-code au sein de notre équipe de documentation.

Docs-as-code

En termes simples, un processus « docs-as-code » consiste à faire évoluer la rédaction comme le développement de code, en s’appuyant généralement sur des plateformes et des outils adaptés aux développeurs. Par exemple, la documentation Snyk utilise la plateforme GitBook, qui applique des processus de modification inspirés de Git, propose une interface de rédaction simple et se synchronise avec un dépôt GitHub pour le contenu stocké dans des fichiers Markdown. 

Ce processus a pleinement facilité les contributions. En supprimant la longue courbe d’apprentissage et les restrictions d’accès associées aux outils de rédaction professionnels, il permet à davantage de personnes de contribuer au contenu, sans frais de licence prohibitifs.

La documentation chez Snyk 

Chez Snyk, nos équipes de développement rédigent une première version de la documentation pour chaque nouvelle fonctionnalité dans l’environnement de rédaction GitBook. Elles s’approprient ainsi le contenu et s’y impliquent, ce qui leur permet de contribuer rapidement, sans transfert manuel ni remise en forme à partir d’autres sources. En lançant la rédaction avant que les fonctionnalités passent en phase de test, nous publions souvent la documentation au moment où elles entrent en bêta fermée. Nos utilisateurs accèdent ainsi rapidement et facilement aux informations.

Nous formons, accompagnons et encourageons tous nos contributeurs, en leur proposant une assistance pendant la rédaction (avec l’outil Grammarly) et en veillant à uniformiser les révisions et les modifications. Chaque nouvelle recrue de l’équipe R&D bénéficie de conseils adaptés et d’un accompagnement par des rédacteurs, afin de savoir comment contribuer et demander de l’aide. Une assistance précoce et l’automatisation sont essentielles pour faire évoluer efficacement la documentation, c’est pourquoi l’approche de Snyk les met à l’honneur.

En bref, Snyk suit deux principes :

• Shift-left : testez votre code plus tôt, dès que vous l’écrivez, et pas seulement avant sa mise en production.

• Shift-down : confiez les tests aux développeurs plutôt qu’à des équipes de sécurité spécialisées. 

Nos processus de documentation suivent le même modèle. La collaboration, le passage à l’échelle et l’automatisation font partie de notre ADN.

Les résultats de notre culture de contribution

En transformant la façon dont Snyk crée sa documentation, nous avons atteint, début 2024, plus de 250 contributeurs actifs. Au cours des deux dernières années, nous avons apporté plus de 6 000 modifications et améliorations à notre documentation, soit près de 10 par jour.

Les équipes s’impliquent et contribuent, et les rédacteurs techniques sont à juste titre considérés comme des facilitateurs des fonctionnalités, et non comme des freins. Nous avons évité les courses de dernière minute pour documenter une fonctionnalité, qui peuvent retarder sa sortie ou produire une documentation de mauvaise qualité (ou les deux).

Nos priorités : parcours, profils et recommandations

Nous nous attachons désormais à améliorer la qualité de notre documentation, à l’adapter aux parcours et aux profils des utilisateurs de Snyk, et à proposer davantage de contenu prescriptif et de recommandations.

Adapter la documentation aux parcours utilisateurs

Nous repensons actuellement l’architecture de l’information de notre documentation. Nous avons toujours proposé une documentation « descriptive » claire pour expliquer comment utiliser les produits Snyk. En revanche, nous proposions peu de documentation « prescriptive » pour recommander les bonnes pratiques ou fournir des exemples détaillés. Faute de structure adaptée aux parcours, aux expériences et aux profils des utilisateurs, ces derniers devaient définir eux-mêmes leur approche de mise en œuvre, sans ces conseils. 

Notre point de départ

Voici notre structure de 2022, axée sur les produits Snyk :

Décrire le parcours

Nous avons désormais une architecture de l’information simplifiée et ciblée, qui correspond au parcours linéaire de l’utilisateur :

Notre parcours de contenu comprend :

• Des sections d’introduction décrivant le début du parcours utilisateur (« onboarding »), notamment un guide de démarrage rapide pour évaluer les fonctionnalités, et une section Mettre en œuvre Snyk pour planifier votre déploiement à plus haut niveau.

• Nous détaillons ensuite les intégrations avec Snyk, notamment les intégrations Git pour connecter vos dépôts de gestion du code source à Snyk, puis les intégrations CI/CD pour vos stratégies de déploiement à long terme.

• Nous abordons ensuite les opérations quotidiennes liées à l’analyse avec Snyk, notamment l’utilisation de chacun des produits Snyk, comme Snyk Open Source.

• La section Administration de Snyk présente les tâches générales d’administration.

• Nous terminons par la présentation de deux domaines autonomes : CLI et API.

Adapter la documentation aux profils utilisateurs 

Nous avons identifié plusieurs profils d’utilisateurs de Snyk qui consultent régulièrement notre documentation : les développeurs, les administrateurs et responsables de mise en œuvre, ainsi que les équipes de sécurité des applications. 

Chaque profil a des besoins différents en matière d’information. Nous voulons donc que notre documentation soit facile d’accès et à parcourir pour tous, avec un accès aux sections les plus pertinentes.

Par exemple :

• Développeurs : nous proposons des contenus Guide de démarrage rapide et Analyser avec Snyk.

• Administrateurs et responsables de mise en œuvre : ils peuvent se concentrer sur la configuration Enterprise et l’administration de Snyk.

• Sécurité des applications : ce profil se concentre sur la section Gestion des risques.

Proposer davantage de recommandations

Au fil des ans, nous avons constitué un vaste savoir-faire pour aider nos clients à déployer Snyk avec succès, de la prise en main à l’utilisation quotidienne. Ce contenu prescriptif comprend des cas d’usage détaillés, des guides pas à pas, des recommandations et d’autres conseils pratiques. Nous rassemblons ces connaissances et publions les contenus correspondants.

Ces contenus aideront tous les utilisateurs à planifier chaque étape de leur parcours avec Snyk. Nous savons également que la croissance de notre marché Enterprise entraîne un besoin accru de contenus de ce type, afin de proposer des supports de formation évolutifs et accessibles et de permettre aux entreprises de déployer efficacement leur propre programme de prise en main de Snyk.

Nous avons commencé à créer ces contenus avec les guides de mise en œuvre de Snyk, dans la section Mettre en œuvre Snyk.

Prochaines étapes

Notre parcours documentaire est loin d’être terminé. 

Nous lançons et préparons de nombreux projets passionnants autour de la documentation pour 2024, notamment :

• Ajouter des éléments narratifs cohérents dans toute la documentation, que nos clients pourront utiliser comme modèles.

• Intégrer une IA utile au parcours utilisateur pour répondre rapidement à vos questions.

• Intégrer le contenu au plus près du parcours utilisateur, pour vous permettre d’accéder à l’aide plus rapidement et plus facilement.

• Ajouter un journal des modifications cohérent et détaillé couvrant toutes les évolutions fonctionnelles de Snyk.

• Enrichir et publier un catalogue complet des messages d’erreur.

Alors, consultez régulièrement la documentation pour en savoir plus !