Docs as Code : Une approche de la documentation axée sur le développement
La documentation est un élément essentiel du cycle de croissance d’un programme logiciel. Elle discute exactement de la manière d’utiliser l’application logicielle et peut inclure des aperçus d’utilisateurs, des références API, des instructions de montage, ainsi que des notes de lancement.
L’automatisation de vos documents est la tendance la plus actuelle car elle permet de gagner du temps, de réduire les erreurs et aussi de garantir l’uniformité. Garder vos documents à jour et également accessibles à toutes les parties prenantes facilite la coopération ainsi que l’amélioration continue.
Docs as code est une méthode d’automatisation de la documentation qui traite la documentation technologique comme du code.
Qu’est-ce que Docs as Code ?
Docs as code est un point de vue de croissance logicielle qui vérifie la documentation technique comme une sorte de code. Il recommande que vous devez traiter la documentation avec la même rigueur et le même processus que le code du programme logiciel.
La suggestion derrière docs as code est de traiter la documentation comme un excellent artefact de la procédure de croissance, en l’incorporant au cycle de vie du logiciel. Cela suggère de traiter la documentation comme un composant intégral de la base de code. Cela signifie mettre sur elle exactement le même contrôle de variation, l’assimilation constante, ainsi que les procédures de dépistage que vous faites au code lui-même.
Dans une configuration régulière de docs as code, vous écrivez la paperasse en données de texte brut, généralement dans un langage de balisage léger comme Markdown, HTML ou reStructuredText. Vous les conservez ensuite dans la même base de données que le code source. Cela permet de manipuler et de suivre très facilement les ajustements apportés tant à l’application logicielle qu’à la documentation. Il contribue également à garantir que les documents dépendent de la date avec la variation la plus récente du code.
Pourquoi vous devriez utiliser Docs as Code
Avant l’utilisation de Docs as Code, les documents étaient fréquemment traités comme étant séparés du code, créés avec différents outils ainsi que des procédures. Cette technique plus lâche entraînait couramment des documents obsolètes et des écarts avec le code. Vous pouvez exploiter plusieurs avantages en adoptant la méthode docs as code.
Collaboration améliorée
La méthode Docs as code permet la collaboration entre les programmeurs, les rédacteurs techniques et divers autres intervenants dans le processus de développement. Étant donné que le référentiel de code abrite la documentation, il est facile pour les différentes célébrations d’ajouter et aussi de faire des ajustements. Cela permet de s’assurer que la documentation est précise, à jour et détaillée.
Une méthode conjointe de documentation permet de s’assurer qu’elle inclut tous les détails pertinents et qu’elle reflète précisément le système de programme logiciel tel qu’interprété par toutes les parties.
Automatisation des processus et accessibilité
Un autre avantage des documents sous forme de code est qu’ils permettent à des dispositifs automatisés de générer et de publier des documents. Un système de développement peut générer instantanément des versions HTML ou PDF des documents à partir d’une simple demande de texte, afin de les publier sur un site Internet ou un site de documents internes. Les documents sont ainsi accessibles à d’autres parties prenantes.
En automatisant le processus de production et de publication de la documentation, docs as code contribue à réduire le temps et les efforts nécessaires pour conserver et publier les documents. Cela permet aux groupes de croissance de se concentrer sur l’amélioration du programme logiciel.
Contrôle des versions
Le stockage de la documentation dans la même base de données de code que le programme logiciel facilite la gestion et le suivi des modifications apportées aux deux.
Vous pouvez utiliser des systèmes de contrôle des variations comme Git pour suivre les modifications de la documentation et également revenir aux versions précédentes si nécessaire. Cela permet de s’assurer que les documents sont exacts et à jour, et de cartographier et d’étudier les ajustements.
Le flux de travail typique de Docs as Code
Le flux de travail typique de docs as code consiste en l’écriture, le contrôle de version, la structure et l’organisation :
Le processus d’écriture
La procédure d’écriture est la première étape d’une opération typique de docs as code. De nombreux rédacteurs techniques ainsi que les ingénieurs de la paperasse utilisent le MarkDown simple, AsciiDoc, ou HTML. Ils créent la paperasse en utilisant des dispositifs comme GitBook et Redocly qui garantissent une procédure fluide.
Contrôle de version pour la documentation
La documentation progresse au fur et à mesure que le code évolue. Vous aurez besoin d’un système sophistiqué de contrôle des variations comme Git, Plastic SCM ou Subversion pour suivre les ajustements de la paperasse afin de simplifier la collaboration et aussi le suivi des versions.
Le processus de construction de la documentation
La procédure de construction comprend la manipulation et aussi la compilation des documents dans ses mises en page de livraison. Celles-ci peuvent être HTML, PDF, EPUB, ou autres. La procédure de paperasse est normalement facilitée en utilisant des générateurs de sites statiques comme Hugo ainsi que Jekyll.
L’hébergement et aussi la distribution de la documentation
La procédure d’hébergement ou de distribution est généralement la dernière étape de la procédure de codage des docs. Ce processus permet de s’assurer que la documentation est fournie au client final ainsi que disponible pour toutes les parties prenantes. Vous pouvez utiliser les pages GitHub ou GitLab ou un portail personnalisé pour disperser votre documentation sur internet.
Vous pouvez automatiser la documentation Go et Java en utilisant GoDoc ainsi que JavaDoc.
L’approche docs as code est en train de transformer la rédaction des documents techniques ainsi que leur gestion.
De nombreux langages de démonstration, dont Go et Java, offrent des dispositifs permettant d’automatiser la documentation à l’aide de remarques sur le code. Go fournit le dispositif Godoc, ainsi que Java offre JavaDoc.
S’abonner à notre newsletter
Qu’est-ce que l’approche docs as code de la documentation ?
Docs-as-code est une approche visant à écrire et à publier de la documentation avec les mêmes outils et processus que les développeurs utilisent pour créer du code. Cette philosophie est devenue plus populaire ces dernières années, en particulier dans les entreprises technologiques.
Quels sont les 4 types de documentation ?
Les quatre types de documentation sont :. les tutoriels orientés vers l’apprentissage.les guides pratiques orientés vers les objectifs.les discussions orientées vers la compréhension.les documents de référence orientés vers l’information.
- tutoriels orientés vers l’apprentissage.
- les guides pratiques axés sur les objectifs.
- discussions axées sur la compréhension.
- des documents de référence axés sur l’information.
Qu’est-ce que la documentation en tant que code DaC ?
Qu’est-ce que la documentation en tant que code (DaC) ? La documentation en tant que code (DaC) est un moyen pour les rédacteurs techniques et les développeurs de créer et de publier des documents en utilisant les mêmes outils et processus que ceux utilisés pour écrire le code. Cette approche gagne rapidement en popularité parmi les équipes logicielles.
Qu’est-ce que la Doc en tant que code ?
Qu’est-ce que la documentation du code ? La documentation du code est le processus par lequel les programmeurs logiciels documentent leur code. C’est une combinaison d’images claires et d’explications textuelles qui décrivent ce que fait une base de code et comment elle peut être utilisée. Elle améliore la lisibilité, la reproductibilité et la convivialité du code.
