Docs as Code chez Linode

Bonjour, je m'appelle Nathan et je fais partie de l'équipe de rédaction technique de Linode. L'une de nos tâches principales est de contribuer et de maintenir la bibliothèque de guides et de tutoriels sur https://www.linode.com/docs, où plus de 1 400 articles sont publiés. Afin de maintenir la qualité du contenu et d'encourager la collaboration dans le processus de rédaction, nous avons adopté une méthodologie docs as code pour notre flux de travail de rédaction.

La documentation en tant que code est une méthodologie dans laquelle les outils utilisés pour écrire la documentation sont les mêmes que ceux utilisés pour écrire le logiciel. Cela inclut :

• Utilisation d'un logiciel de contrôle de version
• Rédaction de fichiers de documentation en texte clair
• Exécution de tests automatisés
• Pratiquer l'intégration et la livraison continues

L'équipe de rédaction technique de Linode a également étendu cette méthodologie en prenant la responsabilité de l'infrastructure en nuage qui héberge notre site Web de documentation.

Pourquoi Docs as Code ?

Le respect de ces pratiques offre une série d'avantages :

• Travailler avec ces technologies permet de resserrer les liens entre l'équipe de rédaction technique et les équipes de développement et d'ingénierie de Linode.
  
• D'autres équipes de Linode peuvent contribuer à divers aspects de notre processus. Par exemple : l'équipe front-end peut aider à mettre à jour le thème/la présentation du site web de la documentation en utilisant les outils avec lesquels ils travaillent déjà, et un membre de l'équipe d'ingénierie peut écrire de nouveaux tests automatisés pour la bibliothèque de la documentation.
  
• Notre équipe rédige fréquemment des guides et des tutoriels sur les technologies utilisées dans notre processus. Le fait de les mettre en œuvre nous permet de mieux les comprendre, ce qui améliore notre capacité à les expliquer.
  
• Nous devons également documenter les produits Linode avec précision, ce qui peut impliquer la révision de la base de code de Linode. La maîtrise des langages et des outils utilisés pour ces projets peut nous aider à mieux les comprendre.

Notre mise en œuvre

Étant donné que la mise en œuvre de cette méthodologie peut varier d'une organisation à l'autre, j'aimerais donner un aperçu détaillé de notre processus :

1. Rédaction : Nos rédacteurs techniques rédigent les nouveaux guides en Markdown. Markdown est utilisé pour représenter un texte riche dans un fichier en texte brut et peut être compilé en HTML par une série d'outils. Markdown est presque universellement adopté dans le développement de logiciels ; par exemple, les fichiers README de GitHub sont écrits en Markdown. Écrire en Markdown signifie également que vous pouvez utiliser n'importe quel éditeur de texte brut, qu'il s'agisse d'éditeurs de bureau modernes tels que Visual Studio Code, Emacs ou Vim. Nous savons que les gens ont des opinions bien arrêtées sur leurs éditeurs de texte préférés, et cette flexibilité permet à un plus grand nombre de personnes de contribuer à notre bibliothèque.
   
2. Aperçu des sites locaux : Les fichiers Markdown de notre bibliothèque sont compilés dans leur représentation HTML finale à l'aide d'une balise générateur de sites statiques. Les sites statiques sont des collections de pages préconstruites qui ne dépendent pas d'une base de données pour être rendues lorsqu'elles sont demandées (comme c'est le cas avec un CMS tel que WordPress). C'est pourquoi un site statique est très rapide à charger. Un générateur de site statique rend un site statique en combinant vos fichiers de contenu (par exemple Markdown) avec un thème que vous spécifiez.
   
   Le site web de documentation de Linode utilise Hugoqui est l'un des Générateurs de sites statiques les plus populaires:
   
   • Hugo propose des méthodes d'installation bien documentées sur de nombreux systèmes d'exploitation, de sorte qu'il n'y a pas de problèmes lors de l'intégration d'un nouvel employé.
     
   • Hugo comprend un serveur web de développement local, de sorte que les auteurs peuvent rendre le site sur leur ordinateur tout en écrivant de nouveaux guides. Ce serveur sera également rechargé en direct chaque fois que l'auteur enregistrera son fichier.
     
   • Hugo est extrêmement rapide, ce qui est un facteur important pour une bibliothèque de notre taille - mon Macbook Pro est capable de compiler les 1400 guides en environ 3 secondes, et la fonction de rechargement en direct est presque instantanée. 
     
   • Les shortcodes d'Hugo nous permettent également d'améliorer nos guides avec des fonctionnalités que Markdown ne permet pas, notamment des notes surlignées et des extraits de code numérotés à la ligne.
     
     
3. Collaboration : La bibliothèque de documents est stockée dans un dépôt Git public hébergé sur GitHub, et chaque auteur maintient une fourche de ce dépôt. Lorsqu'un auteur a terminé la rédaction d'un guide, il valide ses modifications, les transfère vers sa fourche, puis ouvre une demande de téléchargement dans le dépôt principal.
   
   Dans le cadre de notre processus de rédaction, deux membres distincts de l'équipe effectuent une révision technique, puis une révision de copie sur tous les nouveaux guides ou les mises à jour de guides. Ces membres de l'équipe téléchargent la branche de la demande d'extraction, effectuent et livrent leurs modifications, puis les repoussent vers la branche sur GitHub. Git est un autre outil quasi-universel pour le développement, et son utilisation nous permet de tirer parti des meilleures pratiques de collaboration, comme le flux de travail gitflow.
   
   De plus, la popularité de GitHub signifie qu'il dispose d'un grand nombre d'intégrations utiles. En particulier, nous utilisons Netlify pour générer des aperçus automatiques et accessibles au public pour chaque demande d'extraction. Nous avons souvent besoin de demander l'avis de Linodians de différents départements, et ils peuvent voir ces liens Netlify partageables sans avoir à cloner notre dépôt de docs et installer Hugo sur leurs ordinateurs portables.
   
   Enfin, l'hébergement dans un dépôt public ouvre notre bibliothèque aux contributeurs extérieurs, ce que nous apprécions.
   
4. Test : Chaque fois qu'une demande d'extraction est soumise ou mise à jour, une série de tests est exécutée sur le contenu de la demande d'extraction. Ces tests sont exécutés avec Travis CIqui est un service d'intégration continue offrant également une intégration GitHub. Si l'un de ces tests échoue, la demande est temporairement bloquée et ne peut pas être fusionnée :
   
   • Le contenu du guide est vérifié sur le plan de l'orthographe et du style (par exemple, la mise en majuscules des termes techniques). Nous utilisons Vale pour effectuer ces tâches. Il s'agit d'un moteur de recherche open-source conçu pour travailler sur la prose. Lorsque nous avons intégré Vale pour la première fois, il a signalé plus de 500 000 fautes d'orthographe dans notre bibliothèque. Bien qu'un peu embarrassant, le fait de connaître ce chiffre et de pouvoir agir en conséquence nous a donné une grande confiance dans notre contenu et dans notre nouveau système de publication.
     
   • Nous vérifions les liens brisés potentiels entre les guides en utilisant Scrapy, un framework open source Python qui récupère le contenu des sites web. Ce test a été rédigé en collaboration avec un membre de l'équipe d'ingénieurs de Linode. Lors de la première mise en œuvre de Scrapy, nous avons également trouvé un certain nombre de liens brisés que nous avons pu corriger.
     
   • Un autre script Python vérifie que les métadonnées de la première page des guides sont valides et ne contiennent pas d'erreurs de syntaxe. Une section "front matter" erronée peut causer des problèmes lors de la construction du site. En validant cette section, nous pouvons être sûrs que le site s'affichera lors de la mise à jour des serveurs web de production.
     
5. Publication et hébergement : La mise à jour du site web des documents est gérée automatiquement par une collection de scripts déclenchés par certains événements sur GitHub :
   
   • Chaque fois qu'un contenu est fusionné dans la branche master du dépôt principal de la documentation, une notification webhook est envoyée à un serveur web d'étape, qui est un Linode. Ce serveur web de secours extrait alors la branche principale de GitHub et construit le site avec Hugo, avec la racine du document du serveur web comme cible pour le rendu du site. Nous visualisons ce site de démonstration et confirmons que le contenu apparaît comme prévu.
     
     Le serveur de démonstration ne faisait pas initialement partie de notre flux de travail ; il a été construit après qu'un incident ait temporairement endommagé notre CSS/styling lors d'une mise à jour du site de production. En bref, Netlify avait correctement rendu un aperçu de la nouvelle version du site, mais n'avait pas réussi à détecter un problème de style. Cela était dû au fait qu'il utilisait notre pipeline de construction "développement" au lieu de notre pipeline de construction "production" (qui minifie notre CSS et d'autres actifs). Le nouveau serveur de staging est configuré de la même manière que notre serveur de production, il utilise donc également le pipeline de production, et il détectera les erreurs de ce type.
     
   • Pour mettre à jour le site de production, nous créons une nouvelle étiquette de version sur GitHub. Cela déclenche une autre notification webhook qui est envoyée au serveur web de production. Ce serveur exécute un script similaire à celui du serveur de mise en scène, mais il extrait le contenu de la nouvelle balise de publication à la place.
   • Le fait que notre fonction de publication se fasse automatiquement minimise les erreurs humaines qui pourraient se produire si nous devions exécuter ce processus manuellement. Les serveurs de transit et de production sont tous deux gérés par des formules de configuration. Salt ce qui minimise également l'erreur humaine lorsqu'ils ont besoin d'une maintenance ou d'une mise à jour logicielle. Salt est également utilisé par d'autres projets d'infrastructure chez Linode, de sorte que nos serveurs web docs peuvent être gérés en même temps que d'autres parties de la flotte.

L'adoption de cette méthodologie nous a permis de rationaliser considérablement notre flux de travail, mais nous nous efforçons toujours de l'améliorer. Si vous avez des suggestions de mises à jour, n'hésitez pas à nous en faire part ! Je suis sur le Slack Write the Docs sous le nom de nmelehan, tout comme plusieurs autres membres de l'équipe. Si vous souhaitez en savoir plus sur les documents en tant que code, je vous recommande le guide d'Eric Holscher sur le site Write the Docs.