Azure DevOps Wiki + VS Code : Super!

Depuis quelques semaines, je rédige de la documentation pour mon travail autour du DevOps. Nous avons cru bon en équipe d’appliquer ce que l’on prône comme pratique : « Everything as Code ». C’est pourquoi nous avons choisi une approche qui vise à considérer la documentation comme du code. Pour ce faire, nous avons bien entendu opté pour la syntaxe Markdown. Ce « langage » est relativement simple et portable si on utilise les fonctionnalités de base. Pas que je n’ai pas envie de parler de la documentation en tant que code, mais je trouvais intéressant de plutôt partager la démarche qui m’a amené à choisir un ensemble d’outils comme Azure DevOps Wiki et VS Code pour accélérer la mise en place de notre documentation.

Comparaison des plateformes évaluées

L’idée n’est pas d’écrire le résultat complet de l’analyse par laquelle je suis passé, mais je pense que les faits saillants de la comparaison sont intéressants. En effet, différents outils sont disponibles pour rédiger, héberger et publier votre documentation. Certaines plateformes sont Open Source et d’autres sont payantes.

MkDocs

On m’avait déjà parlé de cette plateforme dans le passé. Il s’agit d’une boîte à outils qui permet de générer un site de documentation à partir de fichiers Markdown. Le HTML ainsi obtenu doit alors être publié à l’aide d’un hébergeur ou d’un serveur web quelconque. L’idée n’est pas mauvaise et offre la possibilité de personnaliser l’aspect final et général du site de documentation. Toutefois, il faut être un peu à l’aise en Python ou être prêt à l’apprendre. Comme c’est un des langages les plus populaires dans le monde, ce n’est pas une mauvaise chose! Étant toutefois néophytes dans ce domaine, je n’aimais pas la barrière à l’entrée. Par ailleurs, certaines des équipes avec qui je travaille ont eu des petits problèmes de performance au niveau de la recherche qui peut être longue à s’initialiser. Le moteur de recherche est Lunr.js.

Site MkDocs

DocFx

DocFx est la plateforme de documentation as code de Microsoft. Elle sert à plusieurs de leurs sites de documentation ou est en fait un produit Open Source dérivé de leur vraie plateforme. Son gros avantage est qu’il est plutôt en .NET Core, donc plus facile d’approche que le Python dans mon cas. Cependant, il est aussi basé sur Lunr.js. Comme j’avais peur de vivre les mêmes problèmes de performance que mes collègues, je n’aimais pas l’idée. Le support multilingue prévu pour une nouvelle version prochainement était aussi intéressant.

Pour publier le site en HTML, il faut aussi trouver une manière de l’héberger, ce qui n’est pas intéressant dans l’optique d’un Minimal Valuable Product (MVP). Je voulais valider l’approche « As Code » avant de m’embourber dans les problématiques d’hébergement ou autre.

Site DocFx

Azure DevOps Wiki

C’est alors que j’ai découvert Azure DevOps Wiki. Une plateforme de documentation Wiki fournie avec Azure DevOps. En plus d’être hébergée gratuitement à même notre abonnement Azure DevOps, elle permet de publier les fichiers Markdown directement à partir d’un repo Git.

Publish

On peut choisir la branche de laquelle on veut publier et aussi un sous-répertoire au besoin. Tout changement qui sera inclus dans un commit sera automatiquement en ligne sur le Wiki.

Ce qui est également important dans un site de publication de documentation est d’avoir une bonne navigation. Azure DevOps Wiki permet de structurer la documentation de manière hiérarchique en créant des répertoires dans le repo. C’est plutôt minimal, mais ça « fait la job ». Pour plus de détails sur les options disponibles, consultez la page suivante.

Révisions et collaboration

L’avantage d’utiliser les repos Git pour la documentation vient avec l’utilisation des Pull Request (PR). Auparavant, le meilleur moyen était de distribuer un document à travers un courriel ou par Teams/Slack et de recueillir les commentaires. Il fallait aussi intégrer les commentaires de chacun dans un même document et plusieurs personnes ne pouvaient pas collaborer à la révision en prenant connaissance des commentaires des autres. On aurait peut-être pu utiliser un document en édition partagée, mais cela comporte un certain nombre de défis également.

Avec les PR, on obtient une gestion unifiée des commentaires, la possibilité de désigner des réviseurs qui seront informés par courriel que leur contribution est requise et la possibilité de discuter très tôt de son contenu avec le mode brouillon.

Brouillon

Bref, un excellent outil de collaboration pour de la documentation.

PR

Comment gérer le multilingue ?

Un autre critère de sélection pour notre plateforme était d’être en mesure de gérer les différentes langues d’une manière correcte. Je voulais que la documentation des deux langues puisse faire partie de la même PR afin de comparer le contenu traduit avec l’original et surtout de pouvoir valider que le contenu était fourni dans les deux langues.

Pour ce faire, j’ai opté pour une solution simple : un répertoire racine pour chaque langue. Évidemment, la responsabilité nous incombe de s’assurer que la structure est équivalente dans les deux hiérarchies, mais c’est un compromis acceptable.

Azure DevOps ne supporte pas la gestion des langues lors de la publication. Il faut donc publier deux Wikis distincts : un pour chaque langue. C’est là que prends de l’importance la possibilité de publier un sous-répertoire.

PublishSubfolder

VS Code + Extensions

Pour la création du contenu Markdown, VS Code est un éditeur pas mal du tout si on installe certaines extensions :

  • Markdown All in One :
    Permet plusieurs raccourcis dans l’édition du Markdown comme les effets gras et soulignés, la création de tables des matières et la possibilité d’avoir un panneau de prévisualisation intégré à VS Code.
  • Azure Repos :
    Extension fournie par Microsoft pour gérer les éléments relatifs à Azure DevOps comme les PR.
  • Paste Image :
    Permet de coller une image provenant du presse-papier directement dans le Markdown. Le raccourcir Ctrl + Alt + V crée un fichier dans le même répertoire que le fichier en édition et ajoute un lien où se trouve le curseur.

EditionMD

What’s next ?

Ces outils permettent une mise en place rapide d’un site de documentation. Lorsque des besoins plus spécifiques apparaîtront, on pourrait imaginer de finalement publier le même Markdown avec une des plateformes mentionnées précédemment et, pourquoi pas, intégrer la recherche Bing Search ou QnA Maker d’Azure 😊. Bonne documentation!