Blog
Les Bonnes Pratiques de Rédaction DITA (partie 2)
Certains rédacteurs techniques et spécialistes déclarent qu’il est trop compliqué de rédiger avec DITA et que la courbe d’apprentissage est trop abrupte. D’autres spécialistes et responsables de documentation assurent au contraire qu’ils peuvent avoir des nouveaux rédacteurs productifs sur DITA en deux heures.
Cet article est le deuxième d’une série d’articles ciblant les pratiques de rédaction que les rédacteurs doivent adapter, adopter, ou abandonner.
Nous allons nous attacher ici aux nouvelles pratiques que les rédacteurs doivent adopter lorsqu’ils rédigent avec DITA. Bien sûr, chaque organisation et chaque trajectoire est différente, toutefois, les blocages les plus communs pour les rédacteurs sont axés autour de ces trois points :
- Penser à l’accessibilité
- Créer des alternatives de navigation
- Rédiger pour réutiliser
Rédiger pour de nouveaux publics et de nouveaux modes de livraison
La plupart des rédacteurs devront adopter de nouvelles habitudes à mesure qu’ils devront abandonner l’idée qu’ils sont les responsables d’un certain média de livraison et qu’ils ne maîtrisent pas nécessairement la forme finale du contenu. Le plus souvent, les difficultés proviennent des exigences des nouveaux médias : canaux web, applications sur téléphone, sites mobiles, ou même middleware embarqué.
L’accessibilité – une opportunité pour tous
Les nouveaux médias de diffusion ont des exigences spécifiques sur les contenus et proposent de nouvelles opportunités de traitement. L’accessibilité est l’un des points les plus importants pour l’amélioration de l’expérience utilisateurs et pas seulement pour ceux qui ont des difficultés physiques ou cognitives. L’accessibilité sur le web et les formats numériques est non seulement essentielle, elle peut être une obligation légale si vous travaillez pour les services publics ou pour un public large.
Les principes d’accessibilité pour le web (Web Accessibility Initiative, WAI) sont maintenus par un groupe du consortium W3C : Web Content Accessibility Guidelines Working Group. L’impact pour les rédacteurs DITA réside notoirement dans les principes de balisage afin que les outils de publication puissent comprendre le contenu et le traiter de manière adéquate et efficiente. Le résultat, c’est un contenu que les lecteurs d’écran (et autres dispositifs technologiques d’assistance) peuvent comprendre et parcourir afin de présenter l’information efficacement.
La dernière version 2.1 offre des conseils pour les nouveaux outils d’assistance et les nouveaux écrans et dispositifs de diffusion dont les mouvements, rotations, etc.
Améliorer l’accessibilité des images, listes, figures et tableaux
Images
La règle est de rédiger des descriptions afin de donner la signification des images, graphes, schémas, etc. S’il n’y a rien à dire sur l’illustration, elle ne porte pas de message et peut être supprimée sans difficulté. Les images qui ne portent pas de messages sont non seulement redondantes, elles fatiguent le lecteur. Au final, elles ne sont souvent même pas vues par les utilisateurs.
L’élément figure doit contenir :
- Titre
- Un pointeur hypertexte vers une image
- Un texte alternatif
- Un texte descriptif
Le texte alternatif doit présenter une explication pour les lecteurs d’écran. Les utilisateurs déficients visuels peuvent ainsi entendre la description de l’image. Ainsi, s’il n’y a pas besoin de l’image pour comprendre le contenu, cette image peut soit disparaître, soit, au minimum, ne pas contenir d’alternative textuelle.
Lists
Les rédacteurs doivent également toujours utiliser les éléments de liste et ne pas utiliser de caractères typographiques pour marquer une liste tels les virgules ou point virgules.
Tables
Pour l’accessibilité des tableaux, l’élément table doit contenir :
- Un texte descriptif
- Une identification des en-têtes de ligne et/ou de colonnes1
Ces points sont les plus importants pour que chaque rédacteur fournisse un contenu DITA accessible. Chaque rédacteur devrait prendre connaissance des recommandations de la WAI – celles-ci sont disponibles gratuitement en ligne. Vous noterez que les processus de publication de base du DITA OT prennent en compte un certain nombre de mesure d’accessibilité web, notamment les niveaux de titres, le balisage des liens, etc. mais la lecture fournit néanmoins de bons rappels et des points nouveaux.
Créer des alternatives de navigation
Un chemin narratif est rarement prépondérant dans un set de documentation technique. La norme DITA permet donc aux auteurs de proposer des alternatives de navigation en plus de la table des matières et de l’indexation. L’objectif est ici de permettre un lien direct entre informations connexes pour que les utilisateurs puissent directement naviguer vers d’autres parties de l’information en cliquant sur un simple lien. On peut ainsi ajouter un lien entre une procédure de maintenance et un plan de maintenance, ou encore indiquer un séquencement logique entre plusieurs procédures.
Mais où doit-on placer ces liens ? Si le rédacteur les ajoute dans le corps du texte, les utilisateurs peuvent sortir de la rubrique avant d’en avoir fini la lecture. Cela ajoute un risque car il est possible, voire probable, qu’ils ne reviendront pas pour compléter la procédure ou pour lire la fin de l’information conceptuelle. Nous savons déjà que pour améliorer l’accessibilité, il faut placer les liens supplémentaires en fin de rubrique et cela peut se faire directement dans DITA. Toutefois, la norme offre une possibilité encore plus intéressante pour la création automatique de ces liens : en positionnant ceux-ci au niveau de la carte, permettant ainsi de les supprimer entièrement des rubriques elles-mêmes.
En supprimant ces dépendances entre rubriques, on supprime le besoin de lier systématiquement ces rubriques dans un document.
Les rédacteurs ne doivent jamais s’imaginer connaitre le sens de lecture de l’utilisateur et leur point d’entrée dans la documentation. Évitez d’ajouter des mentions vers des informations externes, par exemple ci-après, comme nous le verrons ensuite, ci-dessous, etc.
Rédiger pour réutiliser
L’une des raisons d’adopter DITA est bien de la possibilité pour les rédacteurs de réutiliser des contenus au lieu de réécrire ou de copier/coller ces contenus.
L’une des raisons d’adopter DITA est bien de la possibilité pour les rédacteurs de réutiliser des contenus au lieu de réécrire ou de copier/coller ces contenus. Les bonnes pratiques2 à adopter sont d’identifier et de séparer d’une part le contenu qui va être publié, et d’autre part le contenu qui va être purement réutilisé.
- Réutiliser des cartes (documents) ou un groupe de rubriques
- Réutiliser des rubriques indépendantes
- Réutiliser des blocs de texte, des segments, des images
- Réutiliser des lettres de l’alphabet (!). Le niveau maximum de réutilisation est la lettre unique, comme on l’entend souvent avec humour.
Le standard vous permet plusieurs méthodes pour réutiliser le contenu, par exemple :
- Réutilisation directe (avec un lien hypertexte)
- Réutilisation de contenu directe par conref
- Réutilisation de contenu indirecte par clé
Les clés sont de plus en plus utilisées ; toutefois, on trouve la combinaison de clés et de conrefs. Cette alliance permet flexibilité et contrôle.
Documenter ses choix dans un guide de style
Finalement, les points à retenir pour les rédacteurs sont bien de a) tester et b) documenter les choix d’architecture, de balises, etc. que vous faites dans votre organisation. Un architecte d’information vous aidera normalement à concevoir un modèle de contenu pour votre équipe. Toutefois, si vous n’avez pas de ressource interne, il est essentiel que vous puissiez embaucher quelqu’un avec l’expérience et la compréhension nécessaire pour aider votre équipe.
Les choix, lorsqu’ils sont validés, doivent être ajoutés à votre guide de style. Vous pouvez vouloir également créer des modèles de contenus pour guider vos rédacteurs. De plus, certains logiciels permettent d’intégrer vos guides dans votre éditeur directement.
Bon à savoir : Comtech Services a contribué à la création d’un modèle de guide de style qui peut vous permettre de démarrer votre propre guide de style3.
—
Retrouvez la première partie de ce blog ici, et découvrez-en la troisième partie, ici.
—
Ce blog a été initialement publié dans la lettre d’information de CIDM, CIDM Matters.
Ressources
1 Les listes de contrôle et les recommandations d’accessibilité sur le web sont disponibles en ligne sur https://www.w3.org/TR/WCAG20/#content-structure-separation
2 DITA Worst Practices, présentation de Keith Schengili-Roberts https://www.slideshare.net/JackMolisani1/keith-schengiliroberts-dita-worst-practices
3 Modèle de guide de style préparé par Comtech et disponible en ligne à https://github.com/oxygenxml/dim/tree/master/info-model
Auteur du blog
Nolwenn Kerzreho Technical Account Manager at IXIASOFT
Avec plus d’une dizaine d’années d’expérience dans l’industrie de la communication technique, Nolwenn Kerzreho est Responsable Technique de Compte pour IXIASOFT en Europe. Point de contact privilégié de nos partenaires, Nolwenn est basée en France. Elle intervient régulièrement dans les conférences internationales, les colloques et les universités françaises où elle présente DITA depuis 2009. Nolwenn a une expérience internationale dans les domaines de la chimie, Telecom, l’industrie langagière et le développement logiciel.
Vous pouvez contacter Nolwenn sur Twitter à @NolwennIXIASOFT
Inscrivez-vous à notre lettre d’information dès maintenant pour rester informé des tendances de l’industrie techcomm et des dernières actualités IXIASOFT!