Créer un système hybride de gestion des documents
Publié le 18 janvier 2024 par Andrew Owen (6 minutes)
Cette semaine, j’ai écouté un podcast dans lequel l’animateur a commencé par présenter des excuses sincères et l’invité a fait quelques remarques intéressantes sur le paysage actuel des médias sociaux. Le volume est roi. Essayer de faire du journalisme sans le soutien d’une grande publication (en particulier ses vérificateurs de faits et son équipe juridique) est à la fois difficile et risqué. Les journalistes et les créateurs de contenu doivent réfléchir à la manière dont ce qu’ils font se reflète sur leur marque personnelle. L’amalgame entre opinion et faits pose également problème. Les faits alternatifs sont une chose (une mauvaise chose).
Cela m’a donné à réfléchir. Je n’indique pas explicitement mes références sur le blog, mais vous pouvez lire mon profil. Lorsque j’écris sur l’écriture, c’est à partir de l’expérience de toute une vie. En ce qui concerne la documentation technique, j’ai quinze ans d’expérience en tant que communicateur technique. Et pour le développement de logiciels, ce sont les mêmes quinze années passées dans l’industrie, une maîtrise d’informatique et l’intégration dans des départements de recherche et développement. Mais une grande partie de ce que j’écris n’est pas constituée de faits purs. Il s’agit d’opinions éclairées. Il existe d’autres points de vue, et les solutions que je présente ne sont en aucun cas la seule façon de faire les choses. Cela étant dit, voici comment je concevrais un système de gestion des documents “clean sheet” si je devais le faire aujourd’hui.
Dans les articles précédents, j’ai abordé la migration du Markdown vers la rédaction structurée, l’écriture en XML avec DocBook et les raisons pour lesquelles je pense que les outils de codage ne sont pas toujours un bon choix pour les rédacteurs. Si vous disposez d’un service de communication technique bien doté en personnel et que vos rédacteurs peuvent répondre aux exigences de l’intégration et du déploiement continus, et si vous disposez du budget nécessaire, vous devriez probablement opter pour une plateforme de publication dédiée. Mais selon le fournisseur de Linux d’entreprise SUSE, de nombreux projets de documentation évoluent dans l’autre sens, en particulier de DocBook (XML structuré) à Asciidoc (un langage de balisage dérivé du schéma DocBook):
Les produits et les solutions devenant de plus en plus complexes, la documentation doit s’appuyer de plus en plus sur des contributeurs externes. L’obstacle à la contribution est nettement moins important avec AsciiDoc qu’avec DocBook. Un tel changement nécessite non seulement de convertir les sources DocBook en AsciiDoc, mais aussi de modifier la configuration du projet, la chaîne d’outils et d’écrire de nouvelles feuilles de style.
C’est pourquoi, en 2018, elle a ajouté la prise en charge d’Asciidoc à son logiciel libre DocBook Authoring and Publishing Suite. Elle comprend:
AsciiDoc étant un sous-ensemble de DocBook, il peut produire DocBook. Vous pouvez convertir DocBook en AsciiDoc avec DocBook Rx, bien que vous puissiez obtenir de meilleurs résultats avec Pandoc. Cependant, d’après mon expérience, quel que soit l’outil utilisé, les métadonnées ont tendance à ne pas survivre au processus d’aller-retour. Avec les plateformes de publication traditionnelles, le contenu est au format XML et les contributeurs doivent apprendre un nouvel ensemble d’outils. Mais lorsque les contributeurs sont plus nombreux que les rédacteurs, ne serait-il pas plus logique de travailler dans l’autre sens?
Si vos rédacteurs sont à l’aise avec des outils de développement tels que VS Code, c’est une excellente chose. Mais si ce n’est pas le cas, un CMS sans tête pourrait être la solution. Sauf que je n’en connais aucun qui prenne en charge AsciiDoc. Bien que TinaCMS soit open source, si vous avez une équipe de développeurs avec du temps libre, vous pouvez l’ajouter. Il existe des plugins de navigateur et d’IDE qui fournissent un aperçu en direct, mais les rédacteurs doivent toujours travailler en texte brut. Mais il existe un éditeur basé sur le web qui permet aux rédacteurs de travailler en DocBook sans jamais avoir à voir une balise XML. Il s’agit d’une version JavaScript de l’éditeur XML de XML Mind (https://www.xmlmind.com/xmleditor/web_edition.shtml “XMLmind XML Editor Web Edition”) qui fonctionne sur votre réseau local. Ainsi, si l’un de vos rédacteurs est à l’aise avec les IDE, les autres peuvent écrire dans un éditeur convivial, et vous pouvez convertir le DocBook en AsciiDoc.
AsciiDoc est plus largement supporté que je ne l’avais imaginé. GitHub dispose d’un support de prévisualisation intégré. En effet, lorsqu’il s’agit d’automatiser le déploiement, si vos documents sont déjà dans GitHub, vous pouvez utiliser des Actions pour déclencher des déploiements sur des commits de code (ou tout autre critère). Il est également trivial d’ajouter le support des sites statiques générés avec Hugo et hébergés sur Netlify (comme celui-ci). Il existe également un générateur de site de documentation multiréférentiel AsciiDoc dédié appelé Antora. Il dispose d’un certain nombre de fonctionnalités plus communément associées aux systèmes traditionnels de gestion de la documentation:
Mon seul souci avec Antora est qu’il ne semble pas avoir de support de localisation. Même si vous n’avez pas l’intention de traduire votre contenu, il est préférable d’avoir un système qui peut le gérer et qui n’en a pas besoin plutôt que l’inverse.
Si je devais créer un nouveau système de gestion de documents dont la majorité des contributeurs sont des développeurs, voici un résumé de ce à quoi il pourrait ressembler:
Vous aurez remarqué Affinity Suite sur la liste et vous vous posez peut-être des questions à son sujet. Il s’agit d’une alternative à Adobe Creative Suite qui n’utilise pas de modèle de tarification par abonnement. L’idéal est de maximiser la réutilisation du contenu au sein d’une organisation. Mais les besoins des spécialistes du marketing diffèrent de ceux des rédacteurs techniques. Dans ce cas, la conversion du contenu AsciiDoc en Word facilite son importation dans Affinity Publisher. Et les illustrateurs seront bien plus satisfaits d’Affinity Designer et Publisher que des alternatives open source telles que Krita et InkScape.
En conclusion, bien que cette configuration puisse sembler très personnalisée, DocBook est une norme bien établie et les outils sont mûrs. Bien que la configuration initiale puisse nécessiter quelques connaissances spécialisées, la maintenance d’un tel système devrait être à la portée de n’importe quel ingénieur DevOps. Et si, à un moment donné, vous vous retrouvez soudainement avec un département de communication technique bien doté en personnel, il existe un chemin de migration facile vers des solutions de gestion de documents prêtes à l’emploi.