Migration de la documentation
Publié le 7 décembre 2023 par Andrew Owen (4 minutes)
La migration de la documentation d’une plate-forme logicielle à une autre peut être douloureuse. Je me souviens de l’époque où le déplacement d’un document Word entre Mac et Windows posait des problèmes. J’ai commencé à travailler comme rédacteur technique en septembre 2006, un mois après le lancement de Pandoc (le “convertisseur universel de documents”), même si je n’ai appris son existence que bien des années plus tard. Il aurait certainement été utile pour certaines des migrations que j’ai gérées, mais pas toutes:
Pandoc supporte DocBook et Word comme formats d’entrée, mais AsciiDoc n’est supporté que comme format de sortie, et il ne peut pas gérer Flare ou FrameMaker.
En règle générale, la migration la plus difficile consiste à passer d’un contenu non structuré (tel que FrameMaker non structuré) à un contenu structuré (tel que DITA). En effet, en fonction de l’auteur, le matériel source peut nécessiter une édition lourde avant la migration. La migration la plus facile que j’ai effectuée a été celle de AsciiDoc vers DocBook, mais c’est parce qu’AsciiDoc est une manière légère de représenter DocBook. Tout ce que j’ai eu à faire, c’est de corriger quelques erreurs de validation. Mais c’est un cas particulier.
La migration la plus simple que vous aurez à faire sera de passer d’une variante de Markdown à un système plus complexe. De manière peut-être contre-intuitive, la deuxième migration la plus simple que vous ferez sera l’inverse (de complexe à simple). En effet, vous éliminerez les informations de style et les méta-informations, ce qui simplifie grandement le processus. Si vous passez d’un système propriétaire à un autre, la solution la plus simple est probablement de publier au format HTML, puis de faire passer la sortie par Pandoc dans le format de votre choix.
Il convient de noter qu’il existe deux types de documents Word : les anciens au format propriétaire (.doc) et les nouveaux au format XML (.docx). La plupart des outils de migration requièrent le format le plus récent. Si Word est installé localement, vous pouvez utiliser le script Python doc2docx pour convertir par lots les fichiers dans l’ancien format. Lorsque j’ai migré l’ensemble des documents d’un point de vente et d’un système de back-office de Word vers DocBook, je ne connaissais pas Pandoc. Mais je connaissais XSLT. Après avoir exporté toutes les images et sauvegardé les fichiers Word au format XML, j’ai pu écrire une simple transformation pour convertir le contenu en DocBook. On m’a dit que mon successeur avait eu beaucoup plus de facilité à migrer ce contenu vers FrameMaker.
Flare utilise XHTML. Il ajoute également ses propres balises, mais celles-ci sont faciles à identifier. Il est assez simple d’ouvrir un projet entier dans VScode et d’utiliser la recherche et le remplacement pour obtenir un XHTML propre. Vous devriez ensuite être en mesure de le convertir en HTML simple à l’aide de Pandoc. Cependant, Flare et d’autres systèmes complexes disposent de fonctionnalités telles que les extraits de texte et les variables. Vous devrez les exporter séparément et si vous passez d’un système complexe à un autre (qui ne dispose pas de son propre outil d’importation). Il se peut que vous souhaitiez conserver ces informations en dehors de l’outil que vous utilisez, par exemple dans une feuille de calcul Excel.
D’après mon expérience, la migration vers DITA a été la plus douloureuse. La DITA est très restrictive, mais heureusement, j’étais l’auteur original du contenu et, même si j’avais utilisé des outils non structurés, le contenu était bien structuré. Mais j’ai quand même fini par copier et coller le contenu d’un FrameMaker non structuré dans le nouveau système. À ma connaissance, même les systèmes de gestion de contenu modernes ne disposent pas d’outils d’importation directe pour FrameMaker non structuré. J’ai utilisé l’approche du copier-coller parce que, selon mon évaluation, c’était plus rapide et plus simple que l’autre solution, qui aurait consisté à convertir FrameMaker non structuré en FrameMaker structuré dans un premier temps.
La leçon à retenir est que la migration des documents doit être gérée comme n’importe quel autre projet de mise en œuvre de logiciel. Vous avez besoin d’un plan pour passer de l’ancien système au nouveau. Vous avez besoin d’un calendrier réaliste pour y parvenir. Vous devez disposer des ressources nécessaires. Et selon votre rythme de livraison, vous devrez peut-être maintenir les deux systèmes en parallèle pendant un certain temps (ce qui peut nécessiter des ressources supplémentaires).
Enfin, il ne s’agit pas d’une tâche que vous souhaitez effectuer régulièrement. Par conséquent, lorsque vous choisissez un nouveau système, assurez-vous qu’il ne vous enfermera pas et qu’il évoluera pour répondre à vos besoins futurs. Tenez compte du temps qu’il faudra pour former votre équipe de documentalistes à son utilisation. Assurez-vous également qu’il offre une bonne prise en charge de la localisation, même si vous n’avez pas l’intention de localiser votre contenu. Il vaut mieux l’avoir et ne pas en avoir besoin que d’en avoir besoin et ne pas l’avoir.