Qu'est-ce que « Docs as Code » ? Comment rédiger une documentation de code (meilleures pratiques)

```html

Qu'est-ce que « Docs as Code » ?

Dans le paysage en constante évolution du développement logiciel, l'importance d'une documentation claire, concise et maintenable ne peut être surestimée. Traditionnellement, la documentation a souvent été une réflexion après coup, créée et gérée séparément de la base de code, ce qui a conduit à des ressources obsolètes, inexactes et, en fin de compte, inutiles. Cependant, un changement de paradigme est en cours, motivé par la philosophie « Docs as Code ». Cette approche préconise de traiter la documentation avec la même rigueur et les mêmes processus que le code logiciel lui-même, révolutionnant la façon dont les informations techniques sont créées, gérées et consommées.

Cet article explore les concepts de base de Docs as Code, en explorant ses avantages et ses flux de travail courants. De plus, il fournit un guide complet pour rédiger une documentation de code efficace, en décrivant les meilleures pratiques qui garantissent la clarté, la maintenabilité et la convivialité pour divers publics.

Principes de base de Docs as Code

À la base, « Docs as Code » est une approche qui applique les principes, les pratiques et les outils de développement logiciel à la création et à la maintenance de la documentation. Au lieu d'utiliser des traitements de texte traditionnels ou des logiciels de documentation propriétaires, Docs as Code exploite des langages de balisage en texte brut, des systèmes de contrôle de version, des processus de construction automatisés et des flux de travail collaboratifs généralement associés au codage.

Les principes clés qui sous-tendent cette philosophie incluent :

• Formats de texte brut : La documentation est écrite dans des langages de balisage légers comme Markdown, reStructuredText ou AsciiDoc. Ces formats sont lisibles par l'homme, faciles à apprendre et peuvent être facilement convertis en divers formats de sortie (HTML, PDF, etc.).
• Systèmes de contrôle de version (VCS) : Les fichiers de documentation sont stockés et gérés dans un VCS, le plus souvent Git. Cela permet de suivre les modifications, de créer des branches pour de nouvelles fonctionnalités ou des refontes majeures de la documentation, de fusionner les contributions et de revenir aux versions précédentes si nécessaire. Tout comme le code, chaque modification de la documentation est enregistrée, fournissant une piste d'audit claire.
• Collaboration : En utilisant des plateformes VCS comme GitHub, GitLab ou Bitbucket, la documentation devient un effort de collaboration. Les développeurs, les rédacteurs techniques et même les utilisateurs peuvent contribuer, examiner et suggérer des modifications via des mécanismes familiers comme les demandes d'extraction (ou les demandes de fusion).
• Automatisation : Des processus de construction, similaires à ceux utilisés pour compiler du code, sont employés pour transformer les fichiers sources en texte brut en documentation publiable. Cela peut inclure la vérification de la cohérence du style, la validation des liens et le déploiement de la documentation sur un serveur Web ou d'autres canaux de distribution. Les pipelines d'intégration continue/déploiement continu (CI/CD) peuvent automatiser ces tâches chaque fois que des modifications sont poussées vers le référentiel.
• Source unique de vérité : La documentation se trouve aux côtés du code qu'elle décrit, souvent dans le même référentiel. Cette colocalisation permet aux développeurs de maintenir plus facilement la documentation à jour lorsqu'ils modifient le code, réduisant ainsi la probabilité d'une divergence entre le logiciel et ses informations de support.
• Examen et tests : Les modifications de la documentation sont soumises à des processus d'examen, similaires aux revues de code. Cela garantit l'exactitude, la clarté et la cohérence. Des contrôles automatisés (par exemple, pour les liens brisés ou la grammaire) peuvent également être intégrés au flux de travail.

Avantages de l'adoption de Docs as Code

Le passage à un modèle Docs as Code offre une multitude d'avantages pour les équipes de développement et les organisations :

• Amélioration de l'exactitude et des informations à jour : Étant donné que la documentation est gérée aux côtés du code et mise à jour à l'aide des mêmes flux de travail, il est beaucoup plus probable qu'elle reflète l'état actuel du logiciel. Lorsqu'une fonctionnalité change, la documentation associée peut être mise à jour dans le même commit ou la même demande d'extraction.
• Collaboration améliorée : Les développeurs connaissent déjà les systèmes de contrôle de version et les plateformes de codage collaboratives. Leur appliquer à la documentation abaisse la barrière à l'entrée de leurs contributions. Les rédacteurs techniques et les développeurs peuvent travailler plus facilement ensemble.
• Meilleure gestion des versions et historique : Chaque modification de la documentation est suivie, ce qui permet de voir facilement qui a modifié quoi, quand et pourquoi. Ceci est inestimable pour comprendre l'évolution de la documentation et pour revenir aux états précédents si nécessaire.
• Efficacité et automatisation accrues : Les processus de construction et de déploiement automatisés permettent de gagner beaucoup de temps et d'efforts par rapport aux mises à jour manuelles de la documentation. Les pipelines CI/CD garantissent que la dernière documentation est toujours disponible.
• Cohérence du style et de la mise en forme : Les vérificateurs de style et de style peuvent être intégrés au processus de construction pour appliquer une mise en forme et un style d'écriture cohérents dans toute la documentation.
• Autonomisation des développeurs : Lorsque la documentation est facile à contribuer et à mettre à jour, les développeurs sont plus susceptibles de se l'approprier. Cela conduit à une documentation plus complète et plus conviviale pour les développeurs.
• Réduction des coûts : En tirant parti des outils open source et des flux de travail familiers, les organisations peuvent potentiellement réduire les coûts associés aux logiciels de documentation propriétaires et à la formation spécialisée.
• Documentation dans le cadre de la définition de l'achèvement : L'intégration des mises à jour de la documentation dans le cycle de vie du développement signifie qu'une fonctionnalité n'est pas considérée comme « terminée » tant que sa documentation d'accompagnement n'est pas également complète et examinée.

Flux de travail Docs as Code typique

Un flux de travail Docs as Code courant reflète celui du développement logiciel, favorisant l'agilité et la qualité :

1. Créer ou modifier : Un rédacteur ou un développeur crée un nouveau fichier de documentation ou en modifie un existant à l'aide d'un éditeur de texte brut et d'un langage de balisage choisi (par exemple, Markdown).
2. Valider les modifications : Les modifications sont validées dans un référentiel Git local avec un message de validation descriptif expliquant les modifications.
3. Pousser vers le référentiel distant : Les validations locales sont poussées vers un référentiel distant central (par exemple, sur GitHub, GitLab).
4. Créer une demande d'extraction/fusion : Si les modifications sont importantes ou nécessitent une revue par les pairs, une demande d'extraction (ou une demande de fusion) est créée. Cela lance un processus d'examen formel.
5. Examiner et itérer : Les réviseurs examinent les modifications de documentation proposées, fournissent des commentaires, posent des questions et suggèrent des améliorations directement dans la demande d'extraction. L'auteur peut effectuer d'autres validations pour répondre à ces commentaires.
6. Contrôles automatisés (CI) : Le pipeline d'intégration continue (CI) exécute automatiquement des contrôles prédéfinis sur la documentation. Ceux-ci peuvent inclure des vérificateurs de liens, des vérificateurs de style pour appliquer la cohérence et la validation de la construction pour s'assurer que la documentation peut être générée correctement.
7. Fusionner : Une fois que les modifications sont approuvées par les réviseurs et que tous les contrôles automatisés sont réussis, la demande d'extraction est fusionnée dans la branche de documentation principale.
8. Construire et déployer (CD) : Le pipeline de déploiement continu (CD) construit automatiquement la documentation finale à partir des fichiers sources et la déploie sur la plateforme désignée, telle qu'un site Web de documentation, un générateur PDF ou une base de connaissances interne.

Outils courants dans une pile Docs as Code

L'écosystème Docs as Code repose sur une variété d'outils, dont beaucoup sont open source et largement adoptés dans le développement logiciel :

• Langages de balisage :
• Markdown : Populaire pour sa simplicité et sa facilité d'utilisation.
• AsciiDoc : Plus riche en fonctionnalités que Markdown, adapté à la documentation complexe.
• reStructuredText (reST) : Souvent utilisé avec Sphinx, puissant pour la documentation technique.
• Systèmes de contrôle de version :
• Git : La norme de facto pour le contrôle de version.
• Plateformes VCS (pour l'hébergement et la collaboration) :
• GitHub
• GitLab
• Bitbucket
• Générateurs de sites statiques (SSG) : Ces outils convertissent les fichiers texte brut en sites Web HTML.
• Sphinx : Excellent pour les projets Python et prend en charge reStructuredText de manière extensive ; capable de générer divers formats de sortie.
• MkDocs : Un SSG rapide et simple utilisant Markdown.
• Hugo : Connu pour sa vitesse incroyable, écrit en Go.
• Jekyll : Basé sur Ruby, alimente les pages GitHub.
• Docusaurus : Basé sur Markdown, optimisé pour les sites de documentation avec des fonctionnalités de versionnement et de traduction, développé par Facebook.
• GitBook (outil de ligne de commande ou plateforme) : Peut être auto-hébergé ou utilisé comme service, offre une expérience d'édition conviviale.
• Vérificateurs de style et de style (pour la cohérence et la qualité) :
• Vale : Un vérificateur puissant et configurable pour la prose.
• textlint : Un outil de vérification enfichable pour le texte et Markdown.
• markdownlint : Spécifiquement pour vérifier les fichiers Markdown pour les problèmes de style et de syntaxe.
• Outils CI/CD (pour l'automatisation) :
• Jenkins
• GitLab CI/CD
• GitHub Actions
• CircleCI
• Éditeurs de texte/IDE (avec une prise en charge solide du texte brut et de Git) :
• Visual Studio Code (VS Code)
• Sublime Text
• Atom
• Vim
• Emacs

Comment rédiger une documentation de code : meilleures pratiques

Bien que Docs as Code fournisse le cadre pour gérer efficacement la documentation, la qualité inhérente de la documentation elle-même dépend de la façon dont elle est écrite. Une documentation de code efficace est claire, concise, précise, complète et méticuleusement ciblée sur son public cible. Le respect des meilleures pratiques garantit que votre documentation sert efficacement son objectif.

1. Connaissez votre (vos) public(s)

Avant de rédiger une documentation, il est crucial d'identifier qui la lira. Différents publics possèdent différents niveaux d'expertise technique et ont des besoins distincts. Il est primordial d'adapter votre contenu en conséquence.

Les publics courants incluent :

• Nouveaux développeurs/membres de l'équipe : Ces personnes ont besoin d'aperçus de haut niveau, de guides de configuration complets et de tutoriels d'introduction pour les mettre rapidement à niveau.
• Développeurs expérimentés (au sein de l'équipe) : Ils recherchent généralement des références d'API détaillées, des diagrammes architecturaux approfondis et des explications de la logique complexe ou des implémentations non évidentes.
• Développeurs intégrant votre code (par exemple, un consommateur d'API) : Ce groupe a besoin d'exemples d'utilisation sans ambiguïté, de guides d'authentification et d'autorisation clairs et d'une documentation d'API robuste couvrant les points de terminaison, les formats de requête/réponse et les codes d'erreur.
• Vous futur : L'un des publics les plus importants, mais souvent négligés, est votre futur vous. Une documentation détaillée peut faire gagner beaucoup de temps et d'efforts lors de la révision du code après une longue interruption.
• Testeurs/équipes QA : Ils doivent comprendre la fonctionnalité prévue, les entrées et sorties attendues, les conditions limites et les cas limites potentiels pour concevoir des tests efficaces.
• Utilisateurs finaux (pour la documentation orientée utilisateur) : Ce public a besoin d'explications claires et non techniques sur la façon d'utiliser les fonctionnalités du logiciel. (Bien que cet article se concentre sur la documentation du code, les principes de Docs as Code peuvent s'étendre ici).

Adaptez toujours le langage, le niveau de détail et les types d'exemples fournis pour répondre au public spécifique que vous adressez pour chaque document.

2. Choisissez les bons types de documentation

Un projet logiciel complet nécessite une variété de types de documentation, chacun servant un objectif spécifique. La sélection du format approprié pour les informations que vous devez transmettre est essentielle.

Une suite de documentation robuste peut inclure :

• Commentaires dans le code :
• Objectif : Expliquer le pourquoi derrière un morceau de code spécifique, clarifier les algorithmes complexes, mettre en évidence la logique non évidente ou avertir des pièges potentiels. Ils ne doivent pas simplement reformuler ce que fait le code s'il est évident.
• Meilleures pratiques : Gardez les commentaires concis et précis. Écrivez-les en même temps que le code. Concentrez-vous sur la justification et l'intention, et non sur une traduction littérale du code. Fondamentalement, mettez toujours à jour les commentaires lorsque le code sous-jacent change pour éviter la désinformation.
• Fichiers README :
• Objectif : Fournir un aperçu de haut niveau du projet, d'un module spécifique, d'un microservice ou même d'un répertoire dans la base de code. C'est souvent le premier point d'entrée pour toute personne explorant le code.
• Meilleures pratiques : Un bon README comprend une brève description du projet, les prérequis, les instructions de construction et d'installation, des exemples d'utilisation de base, des directives de contribution et des liens vers une documentation plus détaillée. Il doit être informatif mais relativement court.
• Documentation de l'API :
• Objectif : Décrire comment interagir avec les interfaces de programmation d'applications (API) publiques, y compris les classes, les méthodes, les fonctions et les points de terminaison HTTP. Ceci est essentiel pour les bibliothèques, les frameworks, les microservices et tout service consommable en externe.
• Meilleures pratiques : Pour chaque élément d'API (par exemple, fonction, point de terminaison), documentez méticuleusement son objectif, ses paramètres (nom, type de données, description, s'il est requis, valeurs par défaut), les valeurs de retour (type de données, description, structure), les erreurs ou exceptions potentielles et des exemples d'utilisation clairs et pratiques. Des outils comme Swagger/OpenAPI pour les API REST, ou Javadoc/DocC/Sphinx autodoc pour les bibliothèques de code, peuvent automatiser la génération de cette documentation à partir d'annotations de code source.
• Tutoriels et guides pratiques :
• Objectif : Les tutoriels sont axés sur l'apprentissage, guidant les utilisateurs à travers une série d'étapes pour atteindre un résultat spécifique (par exemple, « Démarrer avec X »). Les guides pratiques sont axés sur les problèmes, fournissant des solutions à des tâches ou des défis spécifiques (par exemple, « Comment configurer Y pour Z »).
• Meilleures pratiques : Décomposez les tâches complexes en étapes séquentielles gérables. Incluez des extraits de code exécutables et montrez clairement les résultats attendus. Commencez par un objectif bien défini.
• Documentation explicative (conceptuelle) :
• Objectif : Expliquer les concepts de haut niveau, l'architecture du système, les décisions de conception, les modèles de données et les principes sous-jacents du logiciel. Ce type de documentation aide les développeurs à comprendre la « vue d'ensemble » et le contexte dans lequel des composants spécifiques fonctionnent.
• Meilleures pratiques : Utilisez des diagrammes (par exemple, des diagrammes d'architecture, des diagrammes de séquence) pour illustrer des relations complexes. Définissez clairement toute terminologie spécialisée. Expliquez la justification des choix de conception importants et les compromis envisagés.
• Guides de dépannage :
• Objectif : Aider les utilisateurs et les développeurs à diagnostiquer et à résoudre les problèmes, les erreurs ou les comportements inattendus courants.
• Meilleures pratiques : Énumérez les problèmes fréquemment rencontrés, leurs causes profondes potentielles et fournissez des solutions ou des solutions de contournement claires, étape par étape.
• Journaux des modifications/notes de version :
• Objectif : Documenter les modifications spécifiques apportées à chaque version publiée du logiciel, y compris les nouvelles fonctionnalités, les corrections de bogues, les améliorations des performances et, surtout, les modifications importantes.
• Meilleures pratiques : Maintenez un format clair et cohérent. Catégorisez les modifications (par exemple, Ajouté, Modifié, Corrigé, Supprimé, Déprécié). Mettez en évidence les modifications importantes pour avertir les utilisateurs qui effectuent une mise à niveau.

3. Écrivez clairement et concisement

La clarté et la concision sont les pierres angulaires d'une documentation efficace. Un texte ambigu ou trop verbeux peut être plus déroutant qu'utile.

• Utilisez un langage simple : Évitez le jargon et les acronymes inutiles. Si les termes techniques sont essentiels, définissez-les clairement dès la première utilisation. Préférez la voix active (par exemple, « La fonction renvoie une liste ») à la voix passive (par exemple, « Une liste est renvoyée par la fonction ») pour plus de directivité.
• Soyez précis et sans ambiguïté : Les déclarations vagues conduisent à des interprétations erronées. Fournissez des détails concrets, des paramètres et des résultats attendus.
• Utilisez des phrases et des paragraphes courts : Cela rend le texte plus facile à numériser, à lire et à digérer, en particulier pour les sujets techniques complexes. Divisez les longs blocs de texte.
• Utilisez des titres, des sous-titres et des listes : Structurez votre documentation de manière logique à l'aide de titres (H2, H3, etc.) pour créer une hiérarchie claire. Les puces et les listes numérotées sont excellentes pour présenter des séquences d'étapes, de fonctionnalités ou d'éléments connexes.
• Maintenez la cohérence : Utilisez une terminologie, une mise en forme (par exemple, pour les extraits de code, les notes, les avertissements) et un ton cohérents dans toute la documentation. Un guide de style peut être inestimable pour y parvenir.

4. Documentez au fur et à mesure (ou presque)

Procrastiner sur la documentation jusqu'à la fin d'un cycle de développement est un piège courant. Cela conduit souvent à des détails oubliés, à des inexactitudes et à un résultat précipité et médiocre.

• Intégrez la documentation dans votre flux de travail : Traitez la documentation comme une partie intégrante du processus de développement, et non comme une réflexion après coup. Incluez des tâches de documentation dans vos sprints ou cycles de développement. Faites de la documentation mise à jour une partie de la « définition de l'achèvement » pour toute nouvelle fonctionnalité, correction de bogue ou modification importante.
• Écrivez des commentaires pendant le codage : Le moment optimal pour expliquer un morceau de code — son objectif, ses complexités ou les raisons de son implémentation spécifique — est lorsque ce code est frais dans votre esprit.
• Rédigez des documents d'API au début de la phase de conception : La création, même d'une ébauche préliminaire de la documentation de l'API avant ou pendant l'implémentation, peut aider à clarifier les interfaces, à identifier les problèmes potentiels et à servir de contrat pour les développeurs.

5. Fournir des exemples significatifs

Pour les développeurs, les exemples de code sont souvent la partie la plus précieuse de toute documentation. Des exemples bien conçus peuvent accélérer considérablement la compréhension et l'adoption.

• Assurez-vous que le code fonctionne : Tous les extraits de code doivent être précis, suffisamment complets pour être compris dans leur contexte et, surtout, ils doivent réellement fonctionner. Testez vos exemples.
• Illustrez des scénarios pratiques : Concentrez-vous sur les cas d'utilisation courants et les problèmes du monde réel que votre code aide à résoudre. Évitez les exemples trop simplistes ou abstraits qui n'offrent aucune valeur pratique.
• Rendez les exemples copiables et collables : Formatez les extraits de code afin que les développeurs puissent facilement les copier et les coller dans leurs propres projets avec un minimum de modifications.
• Expliquez l'exemple : Ne vous contentez pas de fournir du code ; expliquez brièvement ce que fait l'exemple, pourquoi il est pertinent et mettez en évidence les aspects ou configurations importants.
• Gardez les exemples à jour : Cela ne peut pas être trop souligné. Si le code sous-jacent change, les exemples illustrant son utilisation doivent également être mis à jour. Les exemples obsolètes sont trompeurs et frustrants.

6. Utilisez les visuels efficacement

Les diagrammes, les organigrammes, les captures d'écran et autres aides visuelles peuvent souvent transmettre des informations complexes plus efficacement et intuitivement que le texte seul.

• Diagrammes d'architecture : Utilisez-les pour illustrer la structure globale du système, ses composants et leurs interconnexions.
• Organigrammes et diagrammes de séquence : Ceux-ci sont excellents pour montrer la séquence des opérations dans un processus ou l'interaction entre différents modules ou services.
• Captures d'écran (pour la documentation liée à l'interface utilisateur) : Lors de la documentation des interfaces utilisateur ou des outils avec un composant graphique, des captures d'écran annotées peuvent grandement aider les utilisateurs à comprendre les fonctionnalités et la navigation.
• Gardez les visuels simples et clairs : Évitez l'encombrement et les détails inutiles. Assurez-vous que les diagrammes sont lisibles, bien étiquetés et prennent en charge le texte d'accompagnement. Stockez les ressources visuelles avec la documentation (par exemple, dans un dossier assets/images) et contrôlez-les par version.

7. Rendre la documentation détectable

Même la documentation la plus impeccablement écrite est inutile si les utilisateurs ne peuvent pas la trouver lorsqu'ils en ont besoin.

• Emplacement centralisé : Établissez un endroit clair, bien connu et facilement accessible où réside toute la documentation du projet (par exemple, un site Web de documentation dédié, une section de votre plateforme de contrôle de version).
• Implémenter la fonctionnalité de recherche : Pour les ensembles de documentation plus volumineux, une fonction de recherche robuste est cruciale. Les utilisateurs doivent pouvoir trouver rapidement les informations pertinentes à leurs requêtes.
• Fournir une navigation claire : Utilisez une structure logique avec des menus intuitifs, une table des matières complète et des fil d'ariane pour aider les utilisateurs à s'orienter et à naviguer dans la documentation.
• Lier de manière extensive (et intelligemment) : Créez des liens entre les pages de documentation connexes, les références d'API et les sections pertinentes. Cependant, veillez à ne pas créer un « réseau » difficile à naviguer. Les outils Docs as Code peuvent souvent aider à valider les liens pour éviter la « pourriture des liens ».

8. Examiner et itérer régulièrement

La documentation n'est pas un artefact statique ; c'est une entité vivante qui doit évoluer aux côtés du logiciel qu'elle décrit. L'examen et l'itération continus sont essentiels.

• Revue par les pairs : Intégrez les revues de documentation dans votre processus de revue de code standard (par exemple, via des demandes d'extraction). Demandez à d'autres membres de l'équipe (développeurs, rédacteurs, QA) de revoir la documentation pour la clarté, l'exactitude, l'exhaustivité et le respect des guides de style.
• Solliciter les commentaires des utilisateurs : Encouragez les utilisateurs de votre documentation (internes et externes) à fournir des commentaires. Facilitez-leur la tâche de signaler les erreurs, de suggérer des améliorations ou de demander des éclaircissements.
• Planifier des examens périodiques : Pour les composants de base ou la documentation fondamentale, planifiez des examens périodiques (par exemple, trimestriels, semestriels) pour vous assurer qu'elle reste précise, pertinente et à jour, même si le code n'a pas beaucoup changé.
• Mettre à jour en cas de modifications du code : Il s'agit d'un principe fondamental. Si vous modifiez le code, mettez à jour la documentation correspondante dans le cadre du même ensemble de modifications ou de la même tâche. C'est un avantage essentiel de l'approche Docs as Code.

9. Automatiser dans la mesure du possible

Tirez parti de l'automatisation pour améliorer la qualité de la documentation, appliquer la cohérence et réduire les efforts manuels, comme le souligne la philosophie Docs as Code.

• Génération de documentation d'API : Utilisez des outils pour générer automatiquement une documentation de référence d'API à partir des commentaires du code source (par exemple, Javadoc pour Java, Doxygen pour C++, Sphinx autodoc pour Python, OpenAPI Generator pour les API REST).
• Vérificateurs de style et de style : Intégrez des outils automatisés dans votre pipeline CI pour vérifier la cohérence du style, la grammaire, l'orthographe et le respect des règles de mise en forme.
• Vérificateurs de liens : Utilisez des outils automatisés pour analyser régulièrement votre documentation à la recherche de liens internes ou externes brisés.
• Constructions et déploiements automatisés : Configurez des pipelines CI/CD pour créer automatiquement votre documentation à partir de la source et la déployer chaque fois que des modifications sont fusionnées, garantissant ainsi que la dernière version est toujours publiée.

10. Documenter les décisions de conception et la justification

Au-delà de la documentation de ce que fait le code et de la façon de l'utiliser, il est souvent extrêmement précieux de documenter pourquoi certaines décisions de conception ont été prises, en particulier pour les choix architecturaux importants.

• Architectural Decision Records (ADR) : Ce sont des documents concis qui capturent les décisions architecturales importantes, le contexte dans lequel elles ont été prises, les alternatives envisagées et les conséquences de l'approche choisie. Les ADR fournissent un contexte historique inestimable pour le développement et la maintenance futurs.
• Expliquer les compromis : Si une approche technique ou un modèle de conception particulier a été choisi plutôt que d'autres, expliquez brièvement le raisonnement et les compromis impliqués (par exemple, performances par rapport à maintenabilité, sécurité par rapport à convivialité).

11. Restez DRY (Ne vous répétez pas)

Le principe « Ne vous répétez pas », bien connu dans le développement logiciel, s'applique également à la documentation. Les informations redondantes sont difficiles à maintenir et peuvent entraîner des incohérences.

• Recherchez une source unique de vérité : Définissez une information (par exemple, un paramètre de configuration, un concept architectural) à un seul endroit canonique.
• Lier ou transclure : À partir d'autres pages de documentation pertinentes, créez un lien vers cette source unique de vérité. Certains outils de documentation avancés prennent également en charge la « transclusion », où le contenu d'un fichier peut être intégré directement dans un autre, garantissant que les mises à jour de la source sont reflétées partout.

12. Écrivez pour un public mondial (le cas échéant)

Si votre logiciel ou votre bibliothèque est destiné à être utilisé par un public mondial, ou si votre équipe de développement est répartie à l'échelle internationale, tenez compte de ces points :

• Utilisez un anglais clair et simple : Évitez les idiomes, l'argot ou les structures de phrases trop complexes spécifiques à une culture, qui pourraient être difficiles à comprendre pour les locuteurs non natifs anglais.
• Envisagez la traduction et la localisation : Si la traduction dans d'autres langues est prévue, l'écriture de la documentation source de manière claire, directe et culturellement neutre peut simplifier considérablement le processus de traduction. Certaines configurations Docs as Code peuvent même aider à gérer et à créer des versions traduites de votre documentation.