La documentation est une partie essentielle du cycle de développement logiciel. Il explique comment utiliser le logiciel et peut inclure des guides de l'utilisateur, des références d'API, des instructions d'installation et des notes de version.
L'automatisation de votre documentation est la dernière tendance car elle peut vous faire gagner du temps, réduire les erreurs et assurer la cohérence. Garder 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 en tant que code?
Docs as code est une philosophie de développement logiciel qui considère la documentation technique comme une forme de code. Cela 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 lui appliquer les mêmes processus de contrôle de version, d'intégration continue et de test que vous appliquez au code lui-même.
Dans une configuration typique de docs as code, vous écrivez la documentation dans des fichiers texte brut, généralement dans un langage de balisage léger comme Markdown, HTML ou reStructuredText. Vous le stockez ensuite dans le même référentiel que le code source. Cela facilite la gestion et le suivi des modifications apportées aux logiciels et à la documentation. Cela permet également de s'assurer que la documentation est à jour avec la dernière version du code.
Pourquoi devriez-vous utiliser Docs comme code
Avant les documents en tant que code, la documentation était souvent traitée comme distincte du code, créée avec différents outils et processus. Cette approche plus lâche a souvent conduit à une documentation obsolète et à des incohérences avec le code. Vous pouvez exploiter plusieurs avantages en adoptant 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. Étant donné que le référentiel de code héberge la documentation, il est facile pour différentes parties de contribuer et d'apporter des modifications. Cela permet de s'assurer que la documentation est exacte, à 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'interprété par toutes les parties.
Automatisation des processus et accessibilité
Un autre avantage de docs as code est qu'il permet à des 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 publication 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 pour maintenir et publier la documentation. Il 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 référentiel de code que le logiciel facilite la gestion et le suivi des modifications apportées aux deux.
Vous pouvez utiliser 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 garantir que la documentation est exacte et à jour, et vous pouvez suivre et auditer les modifications.
Flux de travail typique de documents en tant que code
Le flux de travail docs as code typique comprend l'écriture, le contrôle de version, la création et l'hébergement :
Le processus d'écriture
Le processus d'écriture est la première étape d'un flux de travail docs as code typique. La plupart rédacteurs techniques et les ingénieurs de 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 à mesure que 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 documentation
Le processus de construction implique le traitement et la compilation de la documentation dans ses formats de livraison. Ceux-ci peuvent être 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 documentation
Le processus d'hébergement ou de distribution est généralement la dernière étape des documents en tant que processus de codage. 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 à l'aide de GoDoc et JavaDoc
La philosophie docs as code révolutionne la rédaction et la gestion de la documentation technique.
De nombreux langages de programmation, dont 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.
