Blog
Les Bonnes Pratiques de Rédaction DITA (partie 1)
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 premier d’une série d’articles ciblant les pratiques de rédaction que les rédacteurs doivent adapter, adopter, ou abandonner.
Il y a beaucoup de confusion autour de la difficulté (réelle ou non), de la rédaction avec DITA et l’objectif de ces articles est de clarifier les défis que doivent relever les développeurs d’information et les rédacteurs techniques. Cet article se base pour partie sur mon expérience de formatrice en rédaction DITA auprès deux publics bien particuliers:
- Les développeurs de contenu et des groupes d’experts dans différentes industries, depuis 2007.
- Les étudiants en communication technique dans plusieurs universités françaises, depuis 2008.
La courbe d’apprentissage dépend bien sûr de l’expérience de chaque individu, de la compréhension approfondie des concepts, et du savoir-faire. Toutefois, trois aspects sont essentiels pour tout un chacun, indépendamment de l’expérience.
- Renforcement des bonnes pratiques – des pratiques parfois utilisées inconsciemment, à renforcer ; mais aussi des connaissances familières à appliquer autrement.
- Adoption de nouvelles pratiques – de nouvelles pratiques liées aux responsabilités élargies notamment grâce à la rédaction structurée et modulaire mais aussi à la publication vers de nouveaux formats.
- Laisser tomber des habitudes – cela peut être contre-intuitif, mais laisser tomber certaines pratiques liées à des outils ou à des formats propriétaires est parfois le plus difficile pour les rédacteurs.
Les formateurs et les apprenants peuvent utiliser ces aspects pour évaluer les exigences de formation de chaque groupe. Cet article va parler du premier de ces aspects : Renforcement des bonnes pratiques.
Pour démarrer avec DITA
La plupart des rédacteurs connaissent déjà les modèles, les structures, les styles, la catégorisation, l’identification de document (nomenclatures), et la création de résumés. DITA, standard international ouvert, rend ces aspects essentiels et dans une certaine mesure, contraint les rédacteurs techniques. La clé pour comprendre la rédaction modulaire (ou la rédaction en rubrique) nécessite que les rédacteurs techniques :
- Choisissent clairement quel type d’information1 ils veulent rédiger.
- Utilisent des balises plutôt que des styles pour clarifier le sens des segments de texte.
- Enrichissent les contenus avec des métadonnées qui permettent d’identifier non seulement tout le livrable, mais aussi chaque fragment (pensez à l’indexation).
Comprendre le typage des rubriques
La rédaction modulaire devrait être plus facile à mettre en œuvre pour les rédacteurs qui ont une bonne connaisse des normes et pratiques suivantes :
- Norme transverse ISO-IEC-IEEE 82079-1 2019 Préparation de l’information pour les instructions de produits — Partie 1 : Principes et exigences générales, qui sépare les contenus en informations procédurales (instructions), information conceptuelle, et information de référence.
- Anglais simplifié (Simplified Technical English) – qui sépare les contenus en informations procédurales, information conceptuelle.
- Information mapping®, qui sépare les contenus en informations procédurales, processus, descriptions…
- Les modèles et les patterns communs sur le Web (iFixIt, HowTo…) qui fournissent des structures à l’information procédurale.
Lorsque le type de contenu est établi, le rédacteur suit la structure d’information (le modèle) attendue selon ce type. La structure est largement basée sur le sens commun et les bonnes pratiques de l’industrie de la communication technique.
Baliser plutôt que de mettre en forme pour ajouter du sens aux fragments de texte
Le XML, comme le HTML, est un langage balisé. Cela implique que le texte peut être enrichi avec de l’information à valeur ajoutée. La plupart des rédacteurs ne rédigeront pas eux-mêmes, manuellement, ces éléments. Les modèles de rubriques et les interfaces des éditeurs, avec des actions cliquables, permettent aux rédacteurs de choisir et d’appliquer les bonnes balises facilement.
La plupart des rédacteurs, dans un contexte non structuré, utilisent des styles bien définis pour donner du sens au texte et assigner un objectif à l’information. Ainsi, une citation sera présentée en italique alors qu’en rédaction DITA, les rédacteurs choisiront une balise (ou
Autre exemple, dans l’architecture des rubriques procédurales, on peut trouver une étape comme celle-ci : Étape 1. Créer une nouvelle procédure., qui sera présentée en XML (ou XHTML) dans un élément paragraphe (p) :
Étape 1. Créer une nouvelle procédure.
Ceci sera interprété comme un paragraphe, mais il n’y a pas d’indice permettant d’identifier ceci comme une instruction. Le rédacteur doit ajouter les numéros d’étapes manuellement pour suivre le flux des instructions et doit le mettre à jour à chaque fois que « Créer une nouvelle procédure » est utilisé dans un autre contexte ou une autre série d’étapes. En revanche, avec DITA, on va pouvoir ajouter plus de détails sémantiques, par exemple :
Créer une nouvelle procédure.
Ceci sera interprété comme une instruction, à l’intérieur d’une étape, faisant partie d’une série, et intégrée à une rubrique procédurale. Parce que la mise en forme est séparée du contenu, la numérotation et le mot-clé « Étape » sont ajoutés automatiquement par l’éditeur XML pour proposer une vue améliorée au rédacteur, et injecté au moment de la publication.
Avec DITA, les mots-clés pour les avertissements de sécurité, les notes, les légendages, sont ajoutés et numérotés automatiquement lors du processus de publication.
Catégoriser et libeller l’identification des produits et de l’information
Quelle que soit son industrie, chaque rédacteur doit pouvoir identifier les contenus et les produits qu’il documente. Ces deux aspects sont importants pour identifier tout contenu. Lors du passage à DITA, cette information peut être insérée au niveau de chaque rubrique, ou au niveau de la collection (carte ou sous-carte par exemple). Dans la plupart des cas, la sélection des identifiants, obligatoires ou non, et de la manière dont ils doivent être transférés en DITA sera prise en charge par un architecte d’information ou par un expert DITA sénior.
Il s’agit ici réellement de cartographier l’identification actuelle, mais aussi d’enrichir les rubriques avec tous les identifiants nécessaires, lorsqu’elles sont réutilisées dans la documentation de plusieurs produits différents.
« Les informations de libellé et de catalogage font partie des métadonnées des rubriques ou des collections. Les métadonnées permettent au contenu d’être filtré, listé, traité et manipulé d’autres façons. Choisir des libellés précis permettra de créer des documents plus flexibles.2 »
Le résultat attendu est de fournir aux machines et aux processeurs les moyens d’identifier le contenu et d’appliquer l’optimisation de la recherche, la création de facettes, et gérer l’identification des produits.
Rédiger des résumés pour permettre l’identification des informations aux utilisateurs
La plupart des rédacteurs ayant de l’expérience en rédaction web ou en journalisme connaissent la technique de la pyramide inversée. Cette technique rend le contenu plus accessible, et permet d’améliorer le référencement naturel justement car elle se conforme aux guides d’accessibilité web.
La pyramide inversée se réfère à la structure où l’essentiel (voire la conclusion, selon certains) est fourni en premier. Ainsi, dans ce cas, le premier paragraphe, que l’on trouve immédiatement après le titre, aide les rédacteurs avancés à se souvenir des points clés, et aident tous les utilisateurs à identifier si cette rubrique particulière donnera la réponse à la question qu’ils se posent.
Ces descriptions courtes (ou châpo), sont difficiles à réaliser. Elles doivent être courtes, se concentrer sur les points essentiels de la rubrique, mais ne sont ni une redite du titre, ni du métatexte.
Exemple d’une mauvaise description pour une rubrique appelée Eco Printing :
Les explications ci-dessous concernent les procédures d’impression éco pour l’impression écologique.
Exemple d’une description améliorée de la rubrique Eco Printing :
La fonction Eco limite l’utilisation du papier et du toner. La fonction Eco vous permet d’économiser les ressources et permet une impression plus écologique. Si vous appuyez sur le bouton Eco depuis le panneau de commande, le mode Eco est activé. Par défaut, le mode éco propose Plusieurs pages par côté (2) et Économie de toner.
Exemple d’une bonne description de la rubrique Eco Printing :
Utilisez la fonction Eco pour économiser du papier et du toner. Appuyez sur le bouton Eco du panneau de commande pour activer le mode Eco. Les paramètres par défaut sont Plusieurs pages par côté (2) et Économie de toner.
—-
Ce blog a été initialement publié dans la lettre d’information de CIDM, CIDM Matters.
Les prochains articles parleront de deux autres aspects de la rédaction avec DITA : l’adoption de nouvelles pratiques et l’abandon de certaines habitudes.
Ressources
Amy Schade, Inverted Pyramid: Writing for Compréhension, consulté en ligne, Norman Nielsen Group: https://www.nngroup.com/articles/inverted-pyramid/
Keith Schengili-Roberts, IXIASOFT and Joe Storbeck, JANAS, Short Descriptions Shouldn’t Be a Tall Order: Writing Effective Short Descriptions, consulté en ligne, CIDM: https://www.infomanagementcenter.com/product/short-descriptions-shouldnt-be-a-tall-order-writing-effective-short-descriptions/
Tony Self Dr., DITA Style Guide, Best Practices for Authors, Scriptorium Publishing: https://www.amazon.com/Dita-Style-Guide-Practices-Authors/dp/0982811810
Microsoft Style Guide (en anglais), consulté en ligne : https://docs.microsoft.com/en-us/style-guide/welcome/
Nolwenn Kerzreho, Training technical communication students in structured content using DITA, dans Current Practices and Trends in Technical and Professional Communication, ISTC. https://www.amazon.com/Current-Practices-Technical-Professional-Communication/dp/0950645990/
1 Une rubrique est l’unité de base de l’information, elle doit faire sens toute seule, avoir un objectif précis ainsi qu’une structure stable et reconnaissable au premier coup d’œil.
2 Dr. Tony Self dans Guide de Style DITA – Bonnes pratiques pour les rédacteurs (DITA Style guide, Best Practices for Authors) https://www.ixiasoft.com/documentation/DITA_Style_Guide/fr/Artefact/Authoring_Concepts/c_About_the_Style_Guide.html.
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!