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
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.

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
- 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.
  - Noms de programmes, de scripts et de routines
    Les noms de programmes, de routines, d'API (interfaces de programmation) et de scripts sont identifiés à l'aide des éléments cmdname et apiname.
  - Noms de paramètres et de variables
    DITA compte quatre éléments permettant de différencier paramètres, arguments et variables en fonction du contexte dans lesquels ils sont utilisés.
  - Messages apparaissant dans l'interface utilisateur
    DITA possède quatre éléments qui balisent les messages système, les messages d'erreur et autres sorties d'un système informatique ou d'un équipement d'interface utilisateur.
  - Impressions, sorties numériques et autres systèmes de publication
    Lorsqu'un système, une application ou un équipement informatique produit une publication destinée à être lue, celle-ci est décrite dans DITA par l'élément systemoutput.
  - Marques commerciales et marques de service
    L'élément de marque (tm) permet d'identifier les différents types de marques commerciales et de services et de spécifier le propriétaire de la marque. Bien qu'il soit impossible d'insérer directement l'image d'une marque entre les balises, vous pouvez contourner le problème.
  - Touches du clavier
    Vous devez utiliser l'élément uicontrol pour décrire les touches d'un clavier, et l'élément userinput pour décrire plusieurs touches sur lesquelles l'utilisateur doit appuyer. Vous ne devez pas mettre le nom de la touche entre guillemets ou entre parenthèses.
  - Notes de bas de page
    L'élément note de bas de page (fn) est utilisé afin de désigner les informations supplémentaires qui n'ont pas leur place dans le corps du contenu.
  - L'élément coderef
    L'élément coderef sert à référencer des fichiers tels que les exemples de code, qui sont importés lors de la publication pour être convertis en texte standard. L'élément codeblock est une alternative à l'élément lorsque le code est stocké ou mis à jour dans sa forme originale hors de la source DITA.
  - L'élément text
    L'élément text, présenté dans DITA 1.2, identifie un extrait de texte brut sans signification particulière (ou n'ayant aucune exigence de présentation). Il ne doit être utilisé que lorsqu'aucun autre élément sémantique n'est approprié. L'élément text est presque identique à l'élément ph, mais il ne peut pas contenir d'élément sémantique imbriqué contrairement à l'élément ph qui peut contenir, par exemple, des éléments image.
  - Noms de produits, d'entreprises et autres mots-clés
    Les noms de produits, d'entreprises et les autres noms particuliers sont identifiés par l'élément keyword.
  - Contenu de référence de commandes complexes
    Pour documenter des références de commandes complexes de logiciel, vous pouvez utiliser une combinaison d'éléments phrase DITA pour en décrire la syntaxe. Le balisage peut être adapté aux conventions de mise en forme syntaxique lors du processus de publication.
  - Baliser les langages de balisage
    L'élément phrase de syntaxe (synph) peut être utilisé dans un langage de balisage pour décrire les éléments et les attributs.
  - Phrases avec plusieurs langues
    Les mots sans signification sémantique spécifique qui figurent en plusieurs langues dans le reste de la rubrique peuvent être identifiés en définissant l'attribut xml:lang sur le code international standard de la langue utilisée.
- Dates et caractères spéciaux

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.

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.