🔸 Lorsque j’ai créé mon site Web Coffee Cup au début de 2019, j’ai écrit une page intitulée “Rédaction technique” qui commence par ces mots: “La Rédaction Technique va de pair avec la Programmation” et les phrases suivantes ailleurs: “L’époque où la documentation était rédigée à part du développement dans des unités séparées, utilisant des traitements de texte pour produire du contenu, est révolue. (…) la documentation et le développement vont de paire, la première apportant sont soutien au deuxième.” Dans la version anglaise, que j’ai rédigée antérieurement à la version française, j’utilise le mot de “twin”.
Je dois admettre que je ne connaissais pas le concept, la philosophie “Docs as Code” à ce moment-là. Mon propre concept de “jumeau/paire” est une version simplifiée et de mon cru de cette philosophie qui a pour autant une mise en œuvre bien concrète :
➡️ Utiliser les mêmes outils et étapes pour produire la documentation que celles en usage pour produire du code. La Documentation est ainsi intégrée à l’ensemble du workflow, et le Rédacteur technique est un membre de l’équipe.
⭐ Les bénéfices sont les suivants :
- La phase de documentation n’est pas reportée aux dernières minutes disponibles avant la livraison,
- Le rédacteur technique n’est pas réduit à un expert “MS Word” ayant des compétences d’interviewer,
- Le rédacteur technique utilise les mêmes outils que les développeurs, ce qui facilite les échanges,
- The developer often writes the first / draft version of the documentation, the technical writer being the right person to rewrite, enrich, correct, focusing on her/his content producing skills, Le développeur rédige souvent la première version / l’ébauche de la documentation, le rédacteur technique ayant ensuite pour rôle de réécrire, enrichir, corriger, mettant en oeuvre ses compétences en production de contenu,
- La documentation est à toujours jour et facile à maintenir grâce à des systèmes de contrôle de version tels que Git qui se transforment alors en système de gestion de documents.
Dans cette perspective de coopération, Markdown se trouve être la bonne syntaxe : un langage partagé par les deux parties pour améliorer le travail d’équipe, en dehors de toute considération de style.
Bien sûr, le rédacteur technique a toujours un rôle clé : il garantit un contenu de qualité, des normes d’écriture, réalise des images et des diagrammes de qualité, conçoit l’architecture et la navigation, sait quand et où insérer des liens, insère des notes pertinentes, et bien plus encore.
Merci à tous ceux qui ont développé ce concept et écrit sur le sujet. En tant que rédacteur technique, je vous suis reconnaissante.
