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.

Les descriptions courtes ont plusieurs objectifs dans un document. C'est l'une des raisons pour laquelle il est difficile de catégoriser l'élément shortdesc comme contenu (données) ou métadonnées. Techniquement, l'élément shortdesc est une métadonnée parce qu'il se trouve en dehors de l'élément body de la rubrique.

Pour compliquer encore les choses, DITA comprend un élément similaire sémantiquement parlant, l'abstract, qui a la même fonction que la shortdesc (et qui peut être utilisé comme alternative).

Écrire des descriptions courtes consiste pour l'auteur à clarifier le thème principal de la rubrique. Si vous ne pouvez écrire une description courte en moins de 50 mots, c'est que la rubrique est probablement trop complexe et doit être divisée. Si la description courte n'apporte pas de sens à la rubrique, c'est que celle-ci ne contient probablement pas d'idée cohérente.

Pour chaque rubrique DITA, la description courte doit être concise et complète.