Aller au contenu principal

Guide de style DITA - Bonnes pratiques pour les rédacteurs Bonnes pratiques pour les rédacteurs

Introduction
Types d'information et rubriques
Les cartes DITA
Syntaxe et balisage
Langue et ponctuation
Graphiques et images
Références croisées
Réutilisation de contenu
Métadonnées, traitement conditionnel et indexation
Le processus de documentation DITA
Principes de rédaction DITA

Accueil
Syntaxe et balisage
Utiliser le balisage

Syntaxe et balisage
- Organisation des éléments DITA
  Les éléments DITA sont regroupés en différentes catégories pour faciliter l'organisation et la compréhension des informations.
- Utiliser le balisage
  - ID des éléments
    La plupart des éléments DITA ont un attribut id, utilisé pour identifier de façon unique l'élément lorsque celui-ci est réutilisé. L'attribut id est facultatif dans la plupart des cas, mais l'élément racine de la rubrique fait figure d'exception, puisque l'attribut y est obligatoire.
  - Titres
    Les titres et les en-têtes sont des éléments bien distincts. Chaque rubrique, figure, tableau ou section doit avoir un titre unique qui lui est spécifique.
  - Astuces
    Évitez de tricher en utilisant des contournements de balisage qui cassent les règles de langage DITA ou l'intégrité sémantique.
  - Éléments de commentaires, draft-comment et required-cleanup
    Les normes XML de balisage des commentaires, et les éléments spécifiques à DITA draft-comment et required-cleanup, permettent aux auteurs de laisser des notes, des commentaires et des éditions non-achevées qui seront exclus du document de sortie lors de sa publication.
  - Utilisation de l'attribut class
    L'attribut class est utilisé dans la spécialisation et ne doit pas être modifié par l'auteur DITA. Il ne doit pas être confondu avec l'attribut outputclass.
  - Noms d'éléments similaires
    DITA contient des éléments sémantiques dont les noms sont quasiment identiques à d'autres éléments, tels que keyword et kwd. Ces éléments sont censés être utilisés dans différents scénarios de rédaction.
  - Contrôler l'aspect de la sortie
    Si un élément sans différence sémantique spécifique a besoin d'une mise en forme particulière dans la sortie, vous pouvez lui appliquer l'attribut outputclass.
  - Joindre les données au contenu
    Des métadonnées détaillées associées à un élément DITA peuvent être enregistrées dans des éléments data au sein du contenu.
- Domaines des éléments
  Dans DITA, pour des raisons techniques et organisationnelles, les éléments sont ordonnés en différents domaines.
- Les descriptions courtes
  L'élément de description courte (ou shortdesc) est sans doute le composant le plus important d'une rubrique DITA et il est également l'un des éléments les plus délicats à rédiger.
- Listes
  Une liste a pour objectif d'aider le lecteur à comprendre les séquences d'informations et les collections contenant des informations similaires. Le type de liste utilisé diffère selon les structures d'informations.
- Paragraphes
  Les paragraphes sont les composants fondamentaux des rubriques. Un élément paragraph (p) doit être une unité autonome qui exprime une idée ou un point généralement en deux phrases liées, voire plus. L'élément p doit être utilisé lorsqu'aucun autre élément sémantique bloc ne convient.
- Procédures et étapes
  L'objectif des documents procéduraux est d'expliquer au lecteur comment accomplir certaines tâches. Grâce à sa structure par étapes, le type d'information "tâche" est spécialement conçu pour les procédures.
- Tableaux
  Un tableau sert à structurer, organiser et présenter des données factuelles qui seront utilisées comme information de recherche ou de référence. Il y a deux types de tableaux génériques dans DITA : table et simpletable.
- Phrases
  La sémantique des mots et des phrases dans un contenu DITA est exprimée à travers une large variété d'éléments phrase.
- Dates et caractères spéciaux

Utiliser le balisage

Les concepts et les principes liés au balisage XML en général et au balisage DITA en particulier, sont très nombreux.

Traduction du DITA Style Guide - Best Practices for Authors (Tony Self) www.ditastyle.com.

Hébergé par IXIASOFT. Généré par <oXygen/> XML WebHelp.