La documentation est un élément essentiel du cycle de développement des logiciels. Elle explique comment utiliser le logiciel et peut inclure des guides d’utilisation, des références API, des instructions d’installation et des notes de mise à jour.
L’automatisation de votre documentation est la dernière tendance, car elle permet de gagner du temps, de réduire les erreurs et de garantir la cohérence. Le fait de maintenir votre documentation à jour et accessible à toutes les parties prenantes facilite la collaboration et l’amélioration continue.
Docs as code est une approche de l’automatisation de la documentation qui traite la documentation technique comme du code.
Qu’est-ce que Docs as Code ?
Docs as code est une philosophie de développement logiciel qui considère la documentation technique comme une forme de code. Elle suggère que vous devriez traiter la documentation avec la même rigueur et le même processus que le code logiciel.
L’idée derrière docs as code est de traiter la documentation comme un artefact de première classe du processus de développement, en l’intégrant au cycle de vie du logiciel. Cela signifie traiter la documentation comme une partie intégrante de la base de code. Cela signifie appliquer à la documentation les mêmes processus de contrôle de version, d’intégration continue et de test que pour le code lui-même.
Dans une configuration typique de docs as code, vous écrivez la documentation dans des fichiers de texte brut, généralement dans un langage de balisage léger comme Markdown, HTML ou reStructuredText. Vous la stockez ensuite dans le même référentiel que le code source. Cela facilite la gestion et le suivi des modifications apportées au logiciel et à la documentation. Cela permet également de s’assurer que la documentation est à jour avec la dernière version du code.
Pourquoi vous devriez utiliser Docs as Code
Avant l’utilisation de Docs as Code, la documentation était souvent traitée séparément du code, créée avec des outils et des processus différents. Cette approche plus souple conduisait souvent à une documentation obsolète et à des incohérences avec le code. Vous pouvez tirer plusieurs avantages de l’adoption de l’approche « docs as code ».
Collaboration améliorée
Docs as code permet la collaboration entre les développeurs, les rédacteurs techniques et les autres parties prenantes du processus de développement. Comme le référentiel de code abrite la documentation, il est facile pour les différentes parties de contribuer et d’apporter des modifications. Cela permet de garantir que la documentation est précise, à jour et complète.
Une approche collaborative de la documentation permet de s’assurer qu’elle inclut toutes les informations pertinentes et qu’elle reflète fidèlement le système logiciel tel qu’il est interprété par toutes les parties.
Automatisation des processus et accessibilité
Un autre avantage des docs as code est qu’ils permettent aux outils automatisés de générer et de publier de la documentation. Un système de construction peut générer automatiquement des versions HTML ou PDF de la documentation à partir de fichiers en texte brut pour les publier sur un site Web ou un portail de documentation interne. Cela rend la documentation accessible à un plus grand nombre de parties prenantes.
En automatisant le processus de génération et de publication de la documentation, docs as code permet de réduire le temps et les efforts nécessaires à la maintenance et à la publication de la documentation. Cela permet aux équipes de développement de se concentrer sur l’amélioration du logiciel.
Contrôle de version
Le stockage de la documentation dans le même dépôt de code que le logiciel facilite la gestion et le suivi des modifications apportées aux deux.
Vous pouvez utiliser des systèmes de contrôle de version comme Git pour suivre les modifications de la documentation et revenir aux versions précédentes si nécessaire. Cela permet de s’assurer que la documentation est exacte et à jour, et vous pouvez suivre et auditer les modifications.
Le flux de travail typique de Docs as Code
Le flux de travail typique de Docs as Code comprend l’écriture, le contrôle de version, la construction et l’hébergement :
Le processus d’écriture
Le processus d’écriture est la première étape d’un flux de travail typique de docs as code. La plupart des rédacteurs techniques et des ingénieurs en documentation utilisent de simples MarkDown, AsciiDoc ou HTML. Ils rédigent la documentation à l’aide d’outils tels que GitBook et Redocly qui garantissent un processus fluide.
Contrôle de version pour la documentation
La documentation évolue comme le code évolue. Vous aurez besoin d’un système de contrôle de version sophistiqué comme Git, Plastic SCM ou Subversion pour suivre les modifications de la documentation afin de faciliter la collaboration et le suivi des versions.
Le processus de création de la documentation
Le processus de construction implique le traitement et la compilation de la documentation dans ses formats de livraison. Il peut s’agir de HTML, PDF, EPUB, ou autres. Le processus de documentation est généralement facilité par l’utilisation de générateurs de sites statiques comme Hugo et Jekyll.
Hébergement et distribution de la documentation
Le processus d’hébergement ou de distribution est généralement la dernière étape du processus de codage de la documentation. Ce processus garantit que la documentation est livrée à l’utilisateur final et disponible pour toutes les parties prenantes. Vous pouvez utiliser les pages GitHub ou GitLab ou un portail personnalisé pour distribuer votre documentation sur le web.
Vous pouvez automatiser la documentation Go et Java en utilisant GoDoc et JavaDoc.
La philosophie « docs as code » est en train de révolutionner la rédaction et la gestion de la documentation technique.
De nombreux langages de programmation, y compris Go et Java, fournissent des outils pour automatiser la documentation à l’aide de commentaires de code. Go fournit l’outil Godoc, et Java fournit JavaDoc.
