Les documents en tant que code ne sont pas forcément synonymes de Markdown et de Git
Publié le 19 octobre 2023 par Andrew Owen (9 minutes)
Après presque 15 ans en tant que rédacteur technique pour des sociétés de logiciels, je suis un converti à la philosophie de la documentation en tant que code. Mais si j’aime Markdown et Git (je les utilise pour ce site web), je ne les utiliserais pas pour documenter des logiciels d’entreprise. Je ne bénéficierais pas des avantages des outils de documentation dédiés, tels que la création structurée, la source unique et les PDF de haute qualité, pour n’en citer que quelques-uns. On vous a peut-être dit que vous deviez abandonner vos outils et devenir plus proche d’un développeur pour faire de la documentation en tant que code, mais je ne pense pas que ce soit vrai.
Voici ce que dit [Write the Docs](https://www. writethedocs. org/guide/docs-as-code/ “Docs as Code”):
La documentation en tant que code (Docs as Code) fait référence à une philosophie selon laquelle vous devriez écrire de la documentation avec les mêmes outils que le code.
• Suivi des problèmes • Contrôle de version (Git) • Le balisage en texte brut (Markdown, reStructuredText, Asciidoc) • Revues de code • Tests automatisés
Cela signifie qu’il faut suivre les mêmes flux de travail que les équipes de développement et être intégré à l’équipe produit. Cela permet une culture où les rédacteurs et les développeurs se sentent propriétaires de la documentation et travaillent ensemble pour la rendre aussi bonne que possible.
Il énumère les avantages suivants
Je suis fondamentalement en désaccord avec cette interprétation. Et maintenant, les illustrations en tant que code? Au lieu d’utiliser des outils dédiés, devrions-nous demander à tous les illustrateurs d’écrire des SVG en VScode? Bien entendu, ce n’est pas le cas. Je pense que le problème ici est l’idée erronée que parce que les documents sont du texte et que le code est du texte, il s’agit de la même chose. Les documents ne sont pas du code. Mais c’est un produit livrable et, en tant que tel, il est utile d’aligner le processus de documentation sur le processus de développement.
Tout d’abord, vous devez savoir quel cycle de développement logiciel (SDLC) les développeurs utilisent. S’ils travaillent encore en cascade, il est peu probable que vous soyez appelé à faire de la documentation en tant que code. Mais s’ils pratiquent l’intégration et le déploiement continus (CI/CD), l’agilité ou DevOps, attendez-vous à avoir une discussion à ce sujet tôt ou tard.
Il s’agit d’un domaine dans lequel je suis tout à fait d’accord avec l’orthodoxie. Si les développeurs suivent les problèmes dans Jira, les communications techniques devraient également suivre les problèmes dans Jira. Des documents minimaux devraient faire partie de la “définition de ce qui est fait” chaque fois qu’il y a un changement dans le comportement du logiciel qui affecte un utilisateur. Les développeurs doivent rédiger des descriptions publiques des modifications qui peuvent être automatiquement intégrées dans les notes de mise à jour.
La documentation doit faire l’objet d’un contrôle de version. Cependant, les besoins de la documentation et du code sont différents. Historiquement, l’un des systèmes de gestion des versions les plus utilisés était le système CVS (Concurrent Versions System). Mais en raison de ses limites, il a finalement été remplacé par Subversion (SVN). Subversion est ensuite tombé en disgrâce et a été remplacé par Git. Cependant, le processus de développement de logiciels et le processus de rédaction sont différents et, à moins que vous ne disposiez d’un système de gestion de contenu (CCMS) avec versionnage intégré, Subversion est un meilleur choix.
Dans le cadre du développement de logiciels, les développeurs créent des branches de fonctionnalités et travaillent sur le contenu, en soumettant une demande d’extraction (PR) lorsqu’ils ont terminé. Le code est revu et si la demande est approuvée, le code est fusionné dans la branche principale.
La documentation est plus complexe. Les rédacteurs créent ou mettent à jour le contenu, puis l’envoient pour révision. Mais il y a souvent beaucoup plus d’allers-retours à ce stade. Après révision, le contenu peut avoir besoin d’être traduit. Les traductions doivent être révisées. Lorsque la traduction est terminée, il ne faut pas que la source change. Pour cela, vous avez besoin de verrous, qui sont une fonctionnalité de Subversion mais absents de Git.
Le texte brut (Markdown, reStructuredText et, dans une moindre mesure, Asciidoc) rejette les principaux développements de la rédaction technique depuis la normalisation du SGML en 1986:
Si vous n’avez pas d’autre choix que de travailler directement dans un référentiel, je vous conseille fortement d’installer TinaCMS localement. Vous pouvez utiliser .gitignore pour exclure ses fichiers du dépôt sur lequel vous travaillez. Cela vous donnera l’avantage d’un éditeur plus orienté vers l’écriture et la possibilité d’utiliser des assistants d’écriture basés sur un navigateur comme LanguageTool (les liens pour ces deux outils sont au bas de la page).
Mais si vous faites de la documentation de logiciels d’entreprise, vous devez exiger une solution basée sur XML.Je préfère DocBook, mais même si je n’aime pas DITA, je préférerais l’utiliser plutôt que Markdown à cette fin. La plupart des environnements de développement intégré (IDE) n’ont même pas de correcteur orthographique par défaut.
L’hypothèse est que les revues devraient être faites en utilisant le système PR dans Git. Cependant, il n’y a aucune raison pour que l’étape de révision ne soit pas intégrée dans le flux de travail de l’outil de suivi des problèmes. L’assurance qualité ne révise pas le code source, elle révise le logiciel. Il devrait en être de même pour la revue de la documentation. Les développeurs doivent examiner la documentation publiée, et non la source. Cela signifie simplement que vous devez créer un site de transit pour votre documentation qui ne sera disponible qu’en interne.
Il n’existe aucun moyen automatisé de tester la qualité de la documentation. Tout ce qu’un test peut vous dire, c’est si la documentation existe ou non. Mais l’automatisation est une bonne chose. Même si vous ne faites pas de CI/CD, le déploiement de la documentation dans la zone de stockage devrait faire partie du processus de construction du logiciel. Si vous utilisez des outils sur vos propres serveurs, vous pouvez le faire par script. Si vous utilisez un CCMS pour la documentation, cela peut généralement se faire par le biais d’appels d’API.
Un domaine dans lequel les tests automatisés peuvent être utiles est celui de la validation des liens d’aide contextuelle (CSH). Cependant, vous devez d’abord persuader le produit que chaque fonctionnalité doit avoir son propre lien CSH.
Si vous souhaitez intégrer les rédacteurs aux développeurs, et c’est ce que vous devriez faire, la meilleure façon de procéder est de les regrouper dans un même lieu. Si tout le monde travaille à distance, ils doivent se trouver dans un fuseau horaire avec un chevauchement raisonnable. Si vous travaillez dans un bureau hybride ou complet, les rédacteurs doivent avoir leur bureau dans la même zone que les développeurs. Les rédacteurs doivent assister aux réunions des développeurs, telles que les réunions d’information et les rétrospectives. Et surtout, les budgets des rédacteurs doivent appartenir au produit.
C’est une bonne idée que les rédacteurs puissent empêcher une fonctionnalité d’être fusionnée si elle n’est pas accompagnée de documents, mais je doute qu’il y ait des exemples concrets où cela se produise. Les développeurs sont très protecteurs de leur code, et même l’accès en lecture seule des rédacteurs à un référentiel peut être un défi dans de nombreuses organisations.
Mais le plus important est que les rédacteurs travaillent à la même cadence que les développeurs. Si vous pouvez livrer un logiciel à tout moment, vous devez avoir un délai défini pour la disponibilité des documents. Cela nécessite une planification, mais il est préférable de le faire dans un outil de suivi des problèmes plutôt que dans un référentiel de sources.
Si vous pouvez obtenir de vos développeurs qu’ils rédigent une première version de la documentation, c’est une excellente chose. Mais je soupçonne que l’une des raisons pour lesquelles on pousse les rédacteurs à utiliser des outils de développement est que c’est un chemin de moindre résistance que d’essayer d’amener les développeurs à utiliser des outils de rédaction. Donc, si les développeurs ne veulent pas apprendre de nouveaux outils, demandez-leur de faire la documentation dans l’outil de suivi des problèmes. Utilisez ensuite l’automatisation pour exporter le contenu et générer des documents à partir de celui-ci. Encore une fois, si vous utilisez des outils sur vos propres serveurs, cela peut être scripté ou si vous utilisez un CCMS, cela peut généralement être fait par le biais de l’API.
Lorsque j’ai commencé à apprendre le langage assembleur, j’ai fait ce que tout le monde faisait à l’époque. Le code se trouvait dans un fichier texte monolithique, et j’utilisais des copies de fichiers pour la sauvegarde. C’était un système épouvantable. Ce qui devrait être surprenant, mais qui ne l’est probablement pas, c’est qu’en ce qui concerne la documentation, même les éditeurs de logiciels d’entreprise utilisent encore souvent une approche similaire. Des documents Word monolithiques avec des sauvegardes stockées dans des dossiers sur des disques en réseau. Toute alternative est susceptible d’être une amélioration. Au début de ma carrière de rédacteur technique, les entreprises commençaient à peine à comprendre l’intérêt d’utiliser des référentiels de code pour gérer les documents. Mais nous sommes allés trop loin dans le domaine de la rédaction technique pour abandonner des solutions avancées qui offrent une excellente expérience aux utilisateurs au profit d’une approche simpliste de l’alignement des pratiques de travail. L’idée de base des documents en tant que code est bonne, mais une approche moins dogmatique est nécessaire. Que diriez-vous d’une prise de position à chaud?