2.7. shortdesc

L'élément de description courte (<shortdesc>) apparaît entre le titre et le corps du thème, comme contenu de type paragraphe initial d'un thème, ou il peut être incorporé dans un élément <abstract>. La description courte, qui représente le but ou le sujet du thème, sert également d'aperçu de lien et pour la recherche. Utilisée dans une carte DITA, la description courte de l'élément <topicref> peut servir à remplacer la description courte dans le thème.

Utilisez l'élément <shortdesc> lorsque le premier paragraphe du contenu du thème est assez simple pour convenir comme aperçu de lien ou résumé. Sinon utilisez plutôt l'élément <abstract> pour fournir un contenu plus riche autour de l'élément <shortdesc>. Cf. la section 2.6. abstract pour plus de détails sur le comportement de l'élément <shortdesc> dans un élément <abstract>.

Bien que l'inclusion de l'élément <shortdesc> ne soit pas imposée par DITA ou les outils, il est recommandé pour les thèmes de contenir cet élément. Au cas où un thème ne contient qu'un seul paragraphe, il est alors préférable d'inclure ce texte dans l'élément <shortdesc> et de laisser le corps du thème vide.

La description courte devrait consister en un seul paragraphe concis, contenant une ou deux phrases de moins de 50 mots.

Type Recommandation de contenu
tâche

La description courte devrait expliquer aux utilisateurs ce que la tâche leur aide à accomplir, les avantages de la tâche, ou le but de la tâche. Ne répétez pas simplement le titre. Essayez d'inclure des informations qui aideront les utilisateurs à comprendre quand la tâche est appropriée ou pourquoi la tâche est nécessaire. Évitez de dire l'évidence, par exemple « Vous pouvez utiliser XYZ pour faire A » comme seule déclaration dans la description courte de la tâche A. Dans certains cas, donnez des informations supplémentaires à propos des avantages de la tâche.

N'employez pas de bouts de phrase, mais des phrases complètes. Évitez de commencer les descriptions courtes par des phrases telles que « Ce thème décrit… » ou « Ce thème traite… ».

concept

Introduisez le concept et donnez une réponse concise à la question « Qu'est-ce que c'est ? » et, dans quelques cas, à la question « En quoi est-ce que ça me concerne ? ». Si le concept est nouveau, vous pouvez commencer par une brève définition. Évitez d'employer la description courte pour conduire à un thème ou le développer. Le paragraphe de description courte devrait contenir le point principal du thème conceptuel. La description courte du concept devrait clairement s'appliquer à un concept. Évitez de transformer le thème de concept en une tâche. Ne répétez pas simplement le titre.

N'employez pas de bouts de phrase, mais des phrases complètes. Évitez de commencer les descriptions courtes par des phrases telles que « Ce thème décrit… » ou « Ce thème traite… ».

référence

Décrivez brièvement ce que fait l'élément de référence, ce que c'est, ou pourquoi on l'utilise.

Dans la plupart des cas, employez une phrase complète. Vous pouvez utilisez un fragment de phrase seulement pour un thème très court tel qu'un thème d'interface (API) et chacun de ses sous-thèmes. Employez une formulation cohérente à travers les bibliothèques et les référentiels, afin de pouvoir intégrer sans effort vos informations à celles d'un autre produit.

Contient :

Doctype Modèle de contenu
ditabase, topic, task, reference, concept ( données textuelles ou ph ou codeph ou synph ou filepath ou msgph ou userinput ou systemoutput ou b ou u ou i ou tt ou sup ou sub ou uicontrol ou menucascade ou term ou q ou boolean ou state ou keyword ou option ou parmname ou apiname ou cmdname ou msgnum ou varname ou wintitle ou tm ou image ou data ou data-about ou foreign ou unknown) (un nombre quelconque)
map, bookmap ( données textuelles ou ph ou term ou q ou boolean ou state ou keyword ou tm ou image ou data ou data-about ou foreign ou unknown) (un nombre quelconque)

Contenu par :

Doctype Parents
bookmap topicmeta, bookmeta
map topicmeta
ditabase topic, abstract, concept, task, reference, glossdef
topic topic, abstract
task topic, abstract, task
concept topic, abstract, concept
reference topic, abstract, reference
glossary topic, abstract, concept, glossdef

Héritage :

"- topic/shortdesc " utilisé dans les thèmes, et "- map/shortdesc " utilisé dans les cartes.

Attributs :

Nom Description Type de donnée Valeur par défaut Obligatoire ?
%univ-atts; (%select-atts;, %id-atts;, %localization-atts;) Un ensemble d'attributs liés, décrit à la section 25.7. %univ-atts; entité paramètre sans objet pour une entité paramètre sans objet
%global-atts; (xtrf, xtrc) Un ensemble d'attributs liés, décrit à la section 25.2. %global-atts; entité paramètre sans objet pour une entité paramètre sans objet
class, outputclass Attributs communs, décrit à la section 25.9. Autres attributs DITA communs