Directives pour la création de descriptions courtes

Les descriptions courtes sont difficiles et longues à écrire. Certaines règles permettent de créer une shortdesc plus facilement et d'obtenir des descriptions plus cohérentes.

Ce tableau résume les recommandations de Kris Eberlein dans sa présentation Art of the Short Description, lors de la Conférence Europe DITA en 2007.
À faire : À ne pas faire :
  • Rendez la shortdesc autonome, de sorte que la rubrique ne soit pas dépendante des shortdesc.
  • Faites une shortdesc concise et complète.
  • Limitez-vous à 50 mots et à une ou deux phrases.
  • Utilisez des phrases complètes, sauf pour les rubriques courtes telles que dans la documentation API.
  • Répétez le titre.
  • Indiquez les évidences.
  • Démarrez la shortdesc avec cette rubrique....
  • Utilisez la shortdesc comme une phrase de préambule.

Différentes approches à l'écriture de descriptions courtes sont nécessaires pour les différents types d'information.

Type d'informationDirectives
Task

La shortdesc doit répondre aux questions suivantes : quels sont les avantages de la tâche et quel est son but. Incluez des informations sur le moment où l'utilisateur doit effectuer la tâche (ou pourquoi la tâche est nécessaire). Le cas échéant, incluez des informations sur la personne qui effectue la tâche.

Concept

La shortdesc doit répondre aux questions suivantes : qu'est-ce que c'est et pourquoi dois-je en tenir compte. Commencez avec une définition brève, si le concept n'est pas familier. Assurez-vous que la shortdesc résume l'idée principale de la rubrique.

Reference

La shortdesc doit répondre aux questions suivantes : quels sont les éléments, que font-ils et dans quel but sont-ils utilisés. Utilisez des phrases cohérentes tout au long des documents de sorte que l'information puisse être facilement intégrée dans d'autres publications.