Savez-vous rédiger une « Short Description » ?

Principes Short Description
Principes Short Description

Dans une présentation effectuée par Ray Gallon à la conférence annuelle de la STC et disponible en ligne,
on parle de « Embedded User Assistance Using DITA« .

Il s’agit donc de combiner l’aide en ligne intégrée au logiciel à la conception de documentation sous DITA.

Intéressant, n’est-ce pas ?

On y remarque, dans la diapo n° 22 qui s’intitule « Setting query parameters« , une structure très « DITA Classique » : Title, Short Description, Prerequisites, etc.

Tout est parfait, alors ? Qu’en pensez-vous ?…

  • Analysons chaque élément :

(a) La « <Short Desc> :

« Use this panel to set parameters for all flows in the query » 

Donc, après un titre « Setting query parameters » (Définir les paramètres de requêtes), on indique à l’utilisateur:

« Utilisez ce panneau (cette page ?) pour définir les paramètres de tous les flux dans la requête ».

A votre avis, est-ce que l’utilisateur ne va pas se sentir un peu agacé par cette répétition ? S’il s’arrête, en effet,  sur une section intitulée « Définir les paramètres  de requêtes » c’est qu’il a l’intention de définir les paramètres de requêtes, non ?
Il n’y a pas lieu, donc, de lui répéter cela dans la description.

C’est ce que JoAnn Hackos appelle  les « stem sentences » qui consistent à « repeat  the title for the sake of providing a Short Desc. »

Or le contenu qui devrait figurer dans la Short Description est disponible dans le paragraphe sous les  » prerequisites ».

Pour une information complémentaire sur la conception de Short Description, voir la présentation de Michelle Carey, de chez IBM (voir ci-dessus « DITA Short Description Guidelines »).

(b) Le titre « Setting Query parameters » semble intéressant.

Titre précis : essentiel
Importance du titre

En grattant un peu, on s’aperçoit que l’objectif final de l’utilisateur n’est pas de définir les paramètres, mais plutôt « Defining the first level of filtering » ?

En effet, les paramètres de requêtes lui sont utiles pour obtenir un premier niveau de filtrage (voir la suite du texte). Si l’objectif est de fixer un filtrage, on le met en titre. Ensuite, on détaille la procédure expliquant comment  fixer un filtre.

Tout ceci est bien décrit dans les (bons)  manuels de conception de procédure, basés sur le minimalisme et sur la rédaction DITA !

Concernant la <ShortDesc> incontournable dans vos projets DITA, suivez attentivement les explications de Tony Self sur la nécessité du « thesis statement » (au lieu de la reprise du titre) dans la conception de ces descriptions introductives.

Et voilà, vous êtes armés pour rédiger vos premiers éléments de votre topic !

Laisser un commentaire