Jamais sans ma « Short Description »

Eliminons et nettoyons est le mot d’ordre de nombreux rédacteurs sur le point de migrer leur documentation vers la norme DITA.

C’est ainsi qu’à la conférence DITA Europe 2014 à Munich une participante expliquait que, pour réduire le volume de leur documentation, ses clients désireux de passer au minimalisme… commençaient par éliminer la « Short Description » (un des éléments essentiels du standard DITA).

Sacrilège !

DITA_Best_PracticesEn effet, selon les experts Michelle Carey (co-auteur du guide « DITA Best Practices) et Kristen Eberlein, la « short description » est la partie incontournable d’un bon document procédural. Après le titre de la procédure, il faut OBLIGATOIREMENT une « Short Description ».

Dans la <ShortDesc> on expliquera le POURQUOI de la tâche incluse dans la procédure. Il s’agit de préciser à l’utilisateur quel est l’intérêt pour lui de suivre ces étapes. Il décide ensuite s’il veut poursuivre la lecture et si cela correspond à son besoin d’information.
Tony Self, auteur du DITA Style Guide, détaille tout cela dans son article  « Reflections on Writing Short Description ».

Par ailleurs, au moment de la recherche sur le Web, avez-vous remarqué que, sous le titre de la procédure qui s’affiche, apparait un petit paragraphe, qui, s’il est bien ciselé, présente le condensé de la procédure ? Et bien oui, c’est la « Short Description » ! …alors, ne la cachons pas !

Ne jouons pas au Tartuffe s’écriant  « Cachez ce sein que je ne saurais voir » …Dita

Montrez-nous la « Short Description » !

Résumons…

Si la « Short Description » affiche l’intérêt que représente pour l’utilisateur la procédure annoncée (par le titre), ce n’est certainement pas cela qu’il faut éliminer lorsque l’on cherche à réduire  la masse de documentation. Au contraire. C’est cette partie qui va indiquer à l’utilisateur si cette rubrique correspond à ce qu’il cherche…

Cherchons…

Le mot est tombé : « CHERCHER » (et surtout trouver…).  L’utilisateur ouvre le manuel pour chercher une info précise. Comment l’aider à trouver cette info ? En lui SearchingInformationfournissant :

  • une table des matières précise, bien découpée, basée sur des titres parlants (honnissons les « Introductions », « Généralités », « A propos de… »),
  • un index bien pensé
  • et une Short Description pour voir immédiatement la « substantifique moelle »  de la procédure qu’il s’apprête à lire.

Ce n’est donc pas cela  que le rédacteur formé au minimalisme va supprimer, au contraire. Selon le 4e principe du minimalisme :  (l’utilisateur) « read to locate some information »  (Dr. Hans van der Meij). Pour la trouver, l’utilisateur dispose du titre, mais aussi de la Short Description.

Pas si nouveau que cela…

La Short Description ne date pas de l’avènement DITA, mais trouve son origine dans la recherche universitaire. Dans son étude, datant de 2004, « The Four Components of a Procedure » Dr Hans van der Meij parle d’ajouter, sous le titre de la procédure une « Goal description ». « One has to sell the goal…. By adding an explanation on the value of the goal. The description of the goal should add new information to what is already stated in the title” (and not repeat the title). »

 

 

Laisser un commentaire ?

Anti-spam *

ERIKSON
GSX
COHERIS
SCHLUM
EFFICIENT
OPTIS
INTERSEC
NMJ
TALEND
LYRA
HILL
HORIBA
ERIKSON
GSX
COHERIS
SCHLUM
EFFICIENT
OPTIS
INTERSEC
NMJ
TALEND
LYRA
HILL
HORIBA

logo-bleu

Établissement de formation à la documentation technique

Formatrice : Marie-Louise Flacke

Graduate of the American
University of Paris
Tel. 06 03 20 50 10

… mais que signifie Awel-A-Ben ?

Contact

captcha

BLOG

 

blog-icon

 

 

PRESS

press-icon