Documenter de manière flexible avec DITA
Les logiciels standard sont livrés avec une documentation standard. Pour l'utilisation concrète chez le client, les logiciels sont souvent adaptés aux besoins spécifiques du client. Il en résulte la tâche d'élargir la documentation standard aux fonctions spécifiques au client. La documentation standard donne naissance à une documentation de projet.
Comment faire en sorte que la documentation standard et la documentation de projet soient toujours synchronisées, même en cas de mises à jour et de développement des fonctions standard, et que l'on ne doive pas gérer deux états de la documentation en parallèle ?
Changer de mentalité : Documentation en tant que 'code source', développée de manière agile comme un logiciel
Considérons le logiciel standard, y compris la documentation, comme un projet de développement à part entière.
Ensuite, les sources et les fichiers de notre documentation constituent le code source, par analogie avec le code source de nos logiciels. Dans cette optique, notre documentation est comme un logiciel.
Elle se compose de modules de documentation de ressources de base réutilisables. La documentation est développée comme un logiciel. Idéalement, nous le faisons en parallèle du cycle de développement du logiciel.
Le changement de cet état d'esprit a pour conséquence que la manière dont nous écrivons ou plutôt développons la documentation doit changer.
Dans le scénario que nous esquissons ici, la création de documentation doit s'adapter ou du moins se rapprocher des processus de développement logiciel.
Pour que la création de documentation puisse être intégrée de manière judicieuse dans le développement de logiciels, les outils de création de documentation ne doivent pas s'appuyer sur des formats de données propriétaires (tels que FrameMaker non structuré, InDesign, Word).
Ces formats ne sont pas adaptés parce qu'ils ne peuvent pas être lus à tout moment par des machines sans convertisseurs complexes. Or, c'est précisément ce qui est nécessaire pour notre scénario.
Cela nous amène à XML et donc à la norme DITA, désormais bien établie. La création de documentation basée sur DITA peut accomplir la tâche décrite au début, à savoir 'développer' la documentation standard et la documentation spécifique au projet parallèlement au processus de développement du logiciel.
Une pensée agile et un paysage d'outils qui s'appuie sur des normes établies constituent une bonne base pour réunir les équipes de rédaction technique et de développement. développeursdéveloppeusesdéveloppeurs et développeusesdéveloppeur·se·s sont intégrées dans le processus de développement de la documentation en tant que fournisseurs de contenu. Plus encore : Il est également possible d'intégrer constructeursconstructricesconstructeurs et constructricesconstructeur·rice·s, développeursdéveloppeusesdéveloppeurs et développeusesdéveloppeur·se·s et conseillersconseillèresconseiller et conseillèresconseiller·s externes dans le processus de documentation. Nous pouvons leur fournir des contenus pour une documentation spécifique au projet, sur la base d'une base modularisée et réutilisable.
Voyons avec quels concepts la DITA peut nous aider dans la documentation agile.
Nous nous penchons sur la question : Comment pouvons-nous utiliser des outils déjà bien établis dans le développement de logiciels pour le travail éditorial ?
Utiliser les mécanismes de Reuse dans le DITA pour une création de documentation flexible
La réutilisation est l'un des concepts de base forts de DITA. Et ce sont précisément ces concepts très aboutis et sophistiqués qui nous aident à mettre en œuvre une documentation logicielle spécifique au projet.
Commençons par le mécanisme le plus simple, keyref.
keydef et keyref ne sont rien d'autre que des valeurs de variables que nous déposons dans notre documentation (keydef) et que nous référençons aux endroits appropriés (keyref).
Rien de nouveau, car nous connaissons l'utilisation de ce mécanisme dans Word, FrameMaker et d'autres éditeurs et systèmes.
Toutefois, en DITA, ces variables sont définies dans des fichiers propres et, si nécessaire, dans plusieurs fichiers(Key-Maps). Le simple fait de changer le domaine d'application sous-jacent, le key space, peut modifier le contenu de la documentation. Les fichiers peuvent être échangés pour une publication d'une variante de documentation donnée ou être affichés ou masqués via la gestion des variantes dans le cadre d'un profilage.
Le mécanisme de conref est lui aussi rapidement compréhensible.
Il est possible de référencer des contenus provenant d'un pool de ressources et de les intégrer dans la publication.
Adobe FrameMaker, par exemple, met en œuvre un mécanisme similaire dans la variante non structurée au moyen d'inserts de texte.
Un insert textuel est un fragment enregistré en tant que fichier autonome, qui est ensuite intégré au contenu en tant que copie référencée.
Si l'on modifie ce fragment, tous les contenus dans lesquels ce fragment est référencé ou intégré sont modifiés.
DITA va encore plus loin dans ce domaine : L'adressage à l'aide d'ID dans le sujet de la ressource permet également de n'intégrer qu'une partie déterminée, en commençant par un ID défini et en terminant par un autre ID.
Un seul topic peut ainsi contenir plusieurs ressources qui seront intégrées à différents endroits.
La définition centrale des consignes de sécurité et leur intégration aux endroits pertinents dans le contexte du document/sujet en est un exemple pratique.
En revanche, l'utilisation de conkeyref est un peu plus complexe.
Ce mécanisme combine les deux approches keyref et conref.
Dans la DITA, un fichier de ressources est défini comme variable et l'ID est référencé dans ce topic avec la clé.
Ainsi, en remplaçant une référence à des ressources réutilisables, il est possible de faire appel à d'autres contenus nécessaires pour une variante de la documentation spécifique au projet.
Voici un petit exemple de code pour l'illustrer :
<keydef keys="project.screenshots" href="screenshots.dita" format="dita"/><keydef keys="project.screenshots" href="screenshots-project-A.dita" format="dita"/>Dans les ressources de base, nous renvoyons au pool de ressources screenshots.dita, qui contient nos captures d'écran et éventuellement une partie descriptive des dialogues concernés.
Comme nous sommes dans le pool de base, il peut aussi s'agir de graphiques de substitution. Pour la documentation spécifique au projet, nous échangeons maintenant uniquement la référence au pool de ressources pour les captures d'écran(screenshots-project-A.dita).
Sans une seule modification des ressources de base, nous obtenons les bonnes captures d'écran pour chaque variante de documentation.
Le conref push est alors le haut du panier.
conref push nous permet de réaliser une Content Injection. Cela signifie que lors de l'utilisation de ressources de base dans un contexte de projet concret, des contenus sont ajoutés (injectés) dans la documentation de base.
Pour ce faire, un 'topic' de réutilisation ou plutôt d'injection est créé, dans lequel le contenu est référencé via conref à partir de la documentation de base. L'attribut conaction nous offre trois possibilités d'injecter du contenu dans la documentation. D'une part, nous pouvons utiliser pushbefore et pushafter pour monter le contenu avant le contenu référencé ou après le contenu référencé de l'extérieur. Une troisième possibilité consiste à remplacer complètement un contenu par le contenu spécifique au projet via pushreplace.
La condition pour que cela fonctionne également dans des projets plus complexes et soit compris de la manière la plus intuitive possible est la définition et l'attribution propre ainsi que la dénomination des ID pour le contenu réutilisable et étendu.
Les sections suivantes esquissent deux cas d'utilisation des mécanismes du recours. Il s'agit de textes d'interface et de captures d'écran ainsi que de la gestion des variantes à l'aide du profilage.
Ensuite, nous mettons en lumière les avantages et les possibilités qui découlent de l'approche modifiée et, selon nous, 'moderne' du développement de la documentation parallèlement au développement de logiciels.
Il s'agit ici de la gestion du contenu de la documentation, de la planification de la publication et de l'intégration de personnes externes dans le processus de documentation.
Premier cas d'utilisation : Textes d'interface et captures d'écran
Dans la documentation des logiciels, on utilise souvent des textes qui apparaissent dans les interfaces des logiciels afin d'établir un lien correspondant entre la documentation et le logiciel.
Le traitement de ces textes n'est pas toujours facile, surtout lorsque la documentation doit être traduite en plusieurs langues.
Pour mettre en place proprement ce processus, il faut une interface entre le développement et la rédaction technique.
Lorsqu'un logiciel est state-of-the-art, les textes d'interface sont gérés dans des fichiers de ressources externes, traduits et intégrés dans le logiciel en fonction de la langue.
Il est donc logique de générer Key-Maps à partir de ces fichiers de ressources lors du processus de construction du logiciel. Les contenus appropriés peuvent ensuite être référencés dans la documentation à partir de ces cartes clés. La documentation reste ainsi toujours à jour et correcte.
Certains builds de logiciels vont même jusqu'à générer des captures d'écran de manière automatisée et en partie en fonction de la langue et du projet.
Nous pouvons également utiliser ce mécanisme dans la création de documentation pour créer des topics spécifiques à la langue et au projet, qui référencent ces captures d'écran (voir l'exemple de code source ci-dessus). Grâce au conkeyref, nous pouvons intégrer automatiquement les captures d'écran dans nos différentes documentations de projet.
Deuxième cas d'application : Gestion des variantes
DITA offre la possibilité d'exclure certains contenus lors de l'édition grâce à Profiling.
Une documentation spécifique au client est ainsi générée. Cela se fait par le biais d'attributs. Les mécanismes de profilage sont contrôlés lors de la publication via un DITA-VAL dit .
Les balises de profilage sont possibles dans presque tous les DITA. Si nécessaire, ils peuvent également être élargis en se spécialisant pour répondre à des besoins concrets.
Si l'on considère cette particularité de manière isolée, cela aide déjà à générer une documentation spécifique au projet.
En combinaison avec les mécanismes de réutilisation décrits, les possibilités augmentent encore. En effet, le mécanisme de profilage permet également d'inclure ou d'exclure des topics de recherche ou des cartes clés. Un degré maximal de flexibilité est atteint.
Intégration de la documentation dans le processus de développement logiciel : Gestion des contenus
De nombreux projets logiciels utilisent des systèmes de contrôle de version (VCS), comme GIT, Bitbucket ou (plus classiquement) SVN.
Les VCS offrent ainsi une possibilité de gestion flexible du code source, orientée vers les versions.
Selon notre nouvelle vision, la documentation technique est exactement cela, c'est-à-dire du code source.
C'est pourquoi nous avons besoin d'un gestionnaire de code source. Et ce, en fonction des cycles de sortie de nos logiciels. Une gestion qui nous permet également d'intégrer notre documentation dans les différents niveaux de développement du logiciel.
Si nous procédons ainsi, rien que par la gestion dans les niveaux de développement correspondants, nous avons mis nos versions de documentation en parallèle avec le logiciel.
Cela est particulièrement utile pour notre documentation de projet, car les adaptations spécifiques aux clients sont naturellement en retard sur la dernière version de base du logiciel. La documentation de projet doit donc également pouvoir utiliser les ressources de base des anciennes versions du logiciel.
Cela est possible grâce à l'utilisation de VCS et à l'attribution de certains états de la documentation à certaines versions du logiciel.
Planification de la publication de la documentation : daily/nightly builds
Parce que nous considérons la documentation comme du code source, nous pouvons également considérer le processus de publication comme un processus de construction de logiciel. Dans de nombreux scénarios, les builds de logiciels s'exécutent automatiquement. Ils prennent en compte les tests et les validations, surtout dans le cadre du Test-Driven-Development.
Le DITA Open-Toolkit est un outil gratuit, disponible en open source.
Nous pouvons ainsi intégrer de manière automatisée la génération des différentes variantes de documentation, y compris les éditions spécifiques au projet, dans le processus de construction du logiciel. Nous pouvons ainsi faire suivre la génération de documents à l'étape de travail qui nous fournit les textes logiciels et les captures d'écran actualisés.
De cette manière, nous disposons d'une documentation actualisée au jour le jour et adaptée à l'état du logiciel, en fonction des différentes versions et même, si nécessaire, des différents états intermédiaires du logiciel et de la documentation correspondante.
Le processus de construction de la documentation peut valider le contenu lors d'étapes intermédiaires. Cela peut se faire aussi bien structurellement qu'en ce qui concerne les variables référencées et d'autres éléments du Reuse.
Le résultat est un rapport sur les erreurs ou les problèmes constatés dans le stock de données, qui peuvent être retravaillés au jour le jour si nécessaire (avant que la prochaine version ne soit à la porte).
Intégration de personnes externes dans la création de la documentation
Une fois que nous avons créé et validé les ressources de base, nous les livrons à des tiers, par exemple à conseillersconseillèresconseiller et conseillèresconseiller·s ou constructeursconstructricesconstructeurs et constructricesconstructeur·rice·s. L'idéal serait de fournir des modèles de création à cette livraison. Sur la base des templates, les externes ont la possibilité de créer la documentation du projet, avec la consigne de ne pas modifier les ressources de base.
Dans le cas le plus simple, ils adaptent les variables spécifiques au projet (keyref) dans les fichiers de modèle et ajoutent en annexe des détails spécifiques au projet qui n'ont tout d'abord rien à voir avec le logiciel lui-même.
Lors de l'adaptation du logiciel, c'est-à-dire lors de la configuration ou, si nécessaire, par des extensions de programmation propres, les contenus sont désormais complétés ou remplacés au moyen des mécanismes de réutilisation avancés.
Conclusion : Une documentation adaptée
Comme les logiciels sont déjà structurés en soi, il est possible, dans des cas concrets, de trouver des moyens d'extraire des informations directement du logiciel et de les intégrer dans la documentation.
L'exemple le plus simple est ici celui des textes d'interface du logiciel.
Cette approche est certes complexe et nécessite une courbe d'apprentissage correspondante, notamment lorsque des tiers entrent en jeu.
Les avantages de cette approche sont toutefois évidents : On utilise la documentation standard existante et on fournit une documentation adaptée aux besoins du client.
Pour ce faire, il suffit de modifier ou de remplacer précisément les contenus qui diffèrent en fonction du client. Lors de la prochaine mise à jour du logiciel, les relations ( par ex. conref) seront toujours présentes.
La documentation s'actualise d'elle-même dans la zone standard. De plus, il n'est pas nécessaire de refaire toute la documentation, mais seulement les parties qui ont effectivement changé d'une version à l'autre.
Et qu'en est-il des entreprises qui n'acceptent pas les données xml comme livraison, mais qui attendent Word?
Ce groupe cible peut également être soutenu. Une Word n'est qu'une autre forme de diffusion de contenu. Elle peut être générée sans problème à partir des ressources documentaires DITA existantes.
L'infrastructure décrite ici représente une solution de documentation basée sur des normes établies et des processus et outils généralement déjà existants. Cette solution est intégrée dans le processus de développement logiciel. Y a-t-il une raison de ne pas permettre à vos clientsclientesclients et clientesclient·e·s, conseillersconseillèresconseiller et conseillèresconseiller·s, développeursdéveloppeusesdéveloppeurs et développeusesdéveloppeur·se·s et constructeursconstructricesconstructeurs et constructricesconstructeur·rice·s 'accéder à cette infrastructure en tant que service spécial et de l'intégrer dans votre processus et de la fidéliser ainsi à votre entreprise ?
Ce qui a été décrit ici pour la documentation logicielle peut facilement être transposé aux manuels d'utilisation, aux offres, aux contrats et à d'autres types de documentation.
Notre offre : Conversion de vos documents Word, InDesign, FrameMaker en DITA
Nous vous soutenons dans votre démarche vers une documentation basée sur des standards et ouvrant ainsi de nombreuses possibilités d'automatisation.
