Rédigez de la documentation comme vous développez du code

De nombreux ingénieurs et artisans sont particulièrement attentifs à leurs outils. Pour bien faire un travail, il faut les meilleurs outils et les compétences pour les utiliser. Les meilleurs outils de développement de logiciels peuvent être très puissants lorsqu’ils sont appliqués à d’autres types de création numérique. La Documents en tant que code approche est un excellent exemple. Docs as Code implique la rédaction de documentation à l’aide des mêmes outils et workflows que ceux utilisés pour le développement de code. Les partisans de Docs as Code rapportent que cette méthode conduit à une meilleure documentation tout en allégeant la charge de travail des personnes qui l’écrivent.

Formats de texte et contrôle de source

L’ajustement le plus important lors du passage d’une plate-forme de documentation plus traditionnelle à l’approche Docs as Code est que le contenu est stocké dans un format de balisage basé sur du texte. Ce changement rend tous les outils pour les matériaux textuels disponibles pour générer de la documentation. Que vous choisissiez DocBook, Réductionou un autre langage de balisage, le passage d’un seul outil à l’utilisation d’un format standard et d’une variété d’outils est un grand changement.

Il est vraiment important de trouver des outils qui prennent en charge votre flux de travail. De nombreux développeurs utilisent leurs éditeurs de codage lorsqu’ils travaillent sur des projets Docs as Code. Comme ils sont déjà des utilisateurs de niveau avancé avec cet outil, cela fonctionne bien pour eux. Trouver des outils adaptés aux autres professionnels de l’équipe, tels que les rédacteurs techniques, les éditeurs, les architectes de l’information et les propriétaires de produits de documentation, peut demander plus d’efforts. Quelques options à considérer :

• L’un des nombreux bons éditeurs de démarques disponibles
• Éditeurs de codage avec de bons outils de prévisualisation, ce qui les rend accessibles aux non-codeurs
• Les interfaces Web des services d’hébergement Git populaires, en particulier pour les contributeurs occasionnels

Une fois que le contenu est en toute sécurité dans un format de balisage, le projet peut utiliser un contrôle de source tel que Git, un outil open source avec beaucoup plus de fonctionnalités que la plupart des plateformes de documentation ne peuvent prétendre :

• Un historique des versions clair et détaillé de qui a changé quoi et quand. Si vous avez une bonne culture des messages de validation, vous pourrez peut-être même savoir pourquoi le changement a été effectué.

• Processus de changement parallèles faciles. Travailler dans des branches dans Git signifie que chacun peut apporter toutes les modifications qu’il souhaite et les combiner à la fin.

• Outils avancés de collaboration et de révision. Toutes les plates-formes de contrôle de source sont conçues pour examiner chaque modification en détail et avoir autant de discussions que nécessaire jusqu’à ce que tout le monde soit convaincu que la modification peut se poursuivre.

• Contrôles de qualité automatisés tels que la vérification orthographique et la vérification des liens. Cela permet de gagner du temps et de détecter les erreurs qui pourraient autrement être manquées.

Le contrôle à la source présente de nombreux avantages. Gardez simplement à l’esprit que si vous débutez dans le contrôle de source, il y a une courbe d’apprentissage. Il existe d’excellentes ressources d’apprentissage et des articles pour les écrivains qui peuvent vous aider. Vous pouvez également laisser vos documentaristes curieux trouver le matériel d’apprentissage qui leur convient plutôt que de demander à vos ingénieurs de leur enseigner. (Demandez-moi comment j’ai appris cela – à la dure bien sûr !)

Demandes d’extraction et cycles de révision

Toutes les plates-formes de contrôle de source sont conçues autour du concept de demandes d’extractionparfois aussi appelé demandes de fusion. Quelqu’un, ou une équipe, met en place un ensemble de changements, puis demandes que les changements sont tiré dans le projet principal. À bien des égards, travailler avec de nombreux changements à la fois est plus facile dans la documentation que dans le code. Changer un article à un endroit dans la documentation a moins d’effets secondaires que lorsque vous modifiez le code et constatez que plusieurs autres sections en dépendent.

L’outil de collaboration le plus puissant est le diff, qui montre la différence entre les anciennes et les nouvelles versions d’une manière facile à suivre. Il existe de nombreuses versions de cet outil disponibles pour rendre la vue de comparaison plus facile à consulter : côte à côte, en ligne ou même sous forme de démarque rendue plutôt que simplement de texte. Chaque membre de l’équipe peut utiliser l’outil ou les outils qui lui conviennent le mieux. Par exemple, la vue Web est couramment utilisée pour regarder un petit changement, mais pour quelque chose de plus grand, je voudrais le regarder localement en utilisant vimdiff ou Meld.

Les commentaires de révision peuvent être ajoutés à la modification dans son ensemble ou à des lignes individuelles de la modification proposée. Certains projets adoptent une longueur de ligne maximale, appelée emballage dur, ou commencez chaque phrase sur une nouvelle ligne pour faciliter l’ajout de commentaires à des parties spécifiques d’un bloc de texte. D’autres modifications et commentaires peuvent être ajoutés jusqu’à ce que le processus de révision soit terminé et que la modification soit acceptée. Étant donné que les demandes d’extraction sont affichées dans une file d’attente sur le référentiel du projet, c’est un bon moyen de montrer ce qui est en cours et ce qui nécessite une attention particulière. Les outils permettent aux examinateurs d’ajouter facilement leurs réflexions. En particulier, si vous travaillez avec des publics techniques, il peut être plus facile d’obtenir des avis de ces personnes via les outils qu’ils utilisent quotidiennement.

Intégration et déploiement continus

Le fait que la source de votre documentation soit disponible en texte brut présente de nombreux avantages, tels que la possibilité de trouver facilement chaque occurrence de quelque chose qui doit être modifié et l’utilisation d’outils existants tels que toilettesgrep ou tree pour travailler avec des ensembles de documents potentiellement volumineux. Lorsque vous combinez cela avec une plate-forme de contrôle de source, encore plus d’outils existants deviennent disponibles, et ils sont tous open source.

Une grande amélioration du flux de travail est la possibilité d’avoir un déploiement continu en place. Cela signifie simplement que lorsqu’une pull request est fusionnée dans le projet principal, le projet est immédiatement et automatiquement déployé. Si le changement est assez bon pour être accepté dans le projet, il est également assez bon pour être en direct sur le site de documentation, aidant vos lecteurs. En règle générale, le déploiement continu est configuré avec un serveur d’automatisation distinct, tel que Jenkinsou Crochets Git. Dans tous les cas, le balisage textuel est combiné à la plate-forme Docs as Code (généralement un générateur de site statique tel que Hugo ou Sphinx) pour produire le site Web de documentation, qui est ensuite déployé.

La même automatisation peut être utilisée avant le déploiement pour ajouter d’excellentes vérifications aux demandes d’extraction avant qu’elles ne soient fusionnées. Dans un projet de codage, il est courant d’exécuter des linters de code, des tests et d’autres contrôles de qualité qu’une machine peut effectuer elle-même. Les projets de documentation peuvent recevoir le même traitement, avec des outils comme Vallée pour faire du lin en prose et vérifier les styles de titre, l’orthographe, etc. Il est également utile d’ajouter d’autres outils ici, comme un vérificateur de liens pour s’assurer que tous les liens vont à un endroit valide.

Les outils connus et appréciés des ingénieurs sont de très bons outils, mais ils sont également utiles pour toutes sortes d’autres projets. Pour la documentation, ils contribuent à une efficacité précieuse, en particulier lorsque vous avez besoin que votre documentation évolue à la même vitesse que vos équipes de développement. Tous les outils discutés ici sont open source, vous pouvez donc les essayer par vous-même, les déployer pour une énorme équipe mondiale, ou quoi que ce soit entre les deux. Que votre processus de documentation soit aussi fluide que n’importe quel processus de code.