Du Topic à la tâche
| Introduction à DITA / Rédiger avec DITA | |
Comprendre les notions de spécialisation et de domaines d'utilisation.
Spécialiser, c'est créer un élément (ex. une liste d'outils) qui se comporte, au minimum, comme la structure spécialisée (ex. une liste)
Toute spécialisation ne peut que restreindre le cas d'usage
Toute spécialisation ne peut être utilisée que là où la structure spécialisée était utilisable
La définition de la spécialisation permet une représentation par défaut
L’information peut alors être échangée entre systèmes DITA n’ayant pas obligatoirement toute la connaissance des spécialisations d’origine
Les structures normalisées de base sont à utiliser avec précaution : leur but est d’être spécialisées
La norme permet <p>/<figure>/<p>/<figure> qui ne veut rien dire d’un point de vue rédactionnel
De façon générale, ce n’est pas parce que la DTD le permet que c’est licite
Dans DITA, on ne peut que spécialiser, jamais étendre
L’information de base définit le potentiel de spécialisation
Le « topic de base » ne sert qu’à la spécialisation
Mieux vaut ne jamais l’utiliser en tant que tel
Modèle trop laxiste
Peu d’outils peuvent en garantir une publication cohérente
Le « topic de base » est le point d’ancrage de l’ensemble des types de topic
Du standard
Topics Concept
Topics Task
Topics Reference
De toute spécialisation
Corporate
Sectorielle
Modèle de documents = typage de la structure (DITA)
Cohérence du fonds documentaire
Identifier facilement les objets pour la réutilisation
Avoir des objets rédactionnels adaptés à l’information
séquences de tâches pour une procédure
tableaux pour une information de référence
Refuser des structure inutiles
Utiliser les types pour classer et chercher les informations, dans un contexte de documentation modulaire éclatée
De fait, il peut y avoir davantage de type d’informations que de type de structures
Faciliter l’informatique éditoriale
Programmation par/selon les modèles
L’information de base pour comprendre/décrire :
Peut être utilisé pour définir, expliquer, explorer, mettre en contraste...
Les concepts sont faits pour être lus
Nécessaire en complément de Task ou Reference
Différence entre topic de base et topic Concept
Des contraintes sur la cohérence des contenus :
Si un paragraphe suit une section, il doit également être encapsulé dans une section
Permet d'écrire une procédure opératoire en mode pas à pas
Contient des sections pour :
le contexte d’exécution
les prérequis
les résultats attendus de la tâche
la procédure de clôture
L’ordre des sections dans le corps de la tâche est le suivant :
< prereq > → < context > → < steps > → < result > → < example > → < postreq >
Chacune des sections est optionnelle
Les étapes de procédures peuvent être ordonnées ou non
Des listes de choix peuvent également être proposées
Task est défini pour les besoins de la documentation de logiciel
Dans les prérequis, on ne parlera pas d’outillage, par exemple
<task id="mytask">
<title>Acheter un carnet de tickets de métro</title>
<taskbody>
<steps>
<step>
<cmd>Aller à un guichet</cmd>
</step>
<step>
<cmd>Demander un carnet</cmd>
</step>
<step>
<cmd>Payer</cmd>
</step>
</steps>
</taskbody>
</task>
Information de référence sur un produit, une liste de commandes, un menu, une liste de propriétés
Souvent présenté sous forme de liste de définition, ou sous forme tabulaire
Le body est limité aux composants suivants, dans n’importe quel ordre et nombre :
Tableaux (simples ou standards)
Liste de propriétés (< properties>).
Chaque propriété est décrite par un nom, une valeur et une description
Sections et exemples
Sections syntaxiques ( < refsyn >)
Syntaxe d’une commande ou d’une signature
<reference id="white-swan-hotel">
<title>Hotel Concorde Lafayette</title>
<prolog>
<data name=" coût "> très cher </data>
<data name=" étoiles ">5</data>
</prolog>
<refbody>
<section spectitle="Description">
<p> L’hotel des stars.</p>
</section>
<section spectitle="Localisation">
<p>A Paris, proche du P alais des Congrès .</p>
</section>
<section spectitle=" Equipements ">
<simpletable>
<tbody>...</tbody>
</simpletable>
</section>
</refbody>
</reference>
Entrée glossaire
Contenus de type Learning (nouveau en 1.2)
Overview, plan, training content, etc.
Prévus pour 1.3
Troubleshooting
Permet des structures de type : problème, cause, solution
Améliorations de Learning and Training
Un domaine = un ensemble de structures d’un vocabulaire métier
Structures « bloc »
Structures « inline »
Toujours représentables par spécialisation d’éléments de base (<p>,< list >,<ph>, etc.)
Le standard comprend des éléments spécialisés correspondant à 4 domaines particuliers
Formatages basiques d’un traitement de texte
mises en évidence : <b>, <u> , <i>
<tt> Teletype (à n’utiliser que si aucun autre élément approprié n’est disponible)
indices et exposants : <sub> et <sup>
Programmation
paramètres, variables, opérateurs, séparateurs, délimiteurs, mots-clés, options, séquences, diagramme syntaxique
Logiciel
messages, entrées utilisateur, sorties système
Interface utilisateur
<uicontrol> : tout composant permettant à l’utilisateur de contrôler l’interface : <button>, <menu>, etc.
<wintitle> , <menucascade> , <shortcut> , <screen>
Ajouter des domaines existants à des structures existantes
Etendre les domaines existants
Créer de nouveaux domaines
Créer de nouvelles structures / information type
Dans quel contexte peut-on utiliser seulement les topics de la norme ?
Faut-il toujours spécialiser ?
Penser aux domaines et à l’extension du vocabulaire versus la démultiplication des info-types
Construire des architectures de spécialisation
Coût faible
Forte réutilisation des programmes de publication
XML Author