Cachez cette Short Description que je ne saurais voir !...

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)


SACRILEGE !
_____________________________________ 
 

En 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" ...

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...

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 fournissant :

• 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. En réalité, il s'agit d'une excellente mise en application du 4e principe du minimalisme :  (l'utilisateur) "read to locate some information"  selon Dr. Hans van der Meij. Pour la trouver, l'utilisateur dispose du titre, mais aussi de la Short Description.
_____________________________________

Si vous ne souhaitez pas embourber votre équipe de documentation dans le fatras du

(mauvais) minimalisme (*), jetez un oeil sur le programme d'un atelier de formation "Créer l'information dont on a vraiment besoin". 



_____________________________
(*)  tout le monde en parle, mais personne n'a pris la peine de vérifier...

Combien d'argent ai-je jeté par les fenêtres aujourd'hui ?

En matière de documentation produits, voici trois pistes pour brasser de l'air et dépenser à tour de bras :

• produire un Pdf de 400 pages que personne ne lit
• noircir 180 pages pour décrire les fonctionnalités du produit, en incluant 2 copies d'écran par page, dont plusieurs affichent le bouton OK. Ou alors préciser que l'onglet d'annotation sert à afficher le document annoté !

passer 4 h 45 à rédiger le chapitre "Généralités" ... que l'utilisateur ne va pas lire.

__________________________________________
Suzie-la-Terreur
Et voici Suzie-La-Terreur (terreur des équipes de rédaction) pour qui la documentation

technique, c'est comme l'oie que l'on promène dans les rues de New York : décalée, rutilante, humoristique, hors contexte, futile... risible !

Son manuel sur papier glacé est futile, décalé, risible et inutile parce qu'il ne répond pas aux questions précises telle que "comment faire pour modifier les paramètres sans perdre mes enregistrements précédents" que se pose l'utilisateur.

Par contre, ledit manuel se contente de ressasser les évidences. Sous Software Update, il est effectivement impératif d'ajouter qu'il faut avoir installé la version précédente avant de mettre à jour !

Aucune raison  de se pavaner dans les salles de réunion avec le manuel de 450 pages  si l'utilisateur s'en sert comme rehausseur de siège !

Bien sûr, Suzie-et-son-oie-à-New-York (Photo de Ruth Jacobi, 1928) nous plaisent beaucoup  : elles feraient un excellent fond d'écran . 
__________________________________________
Suzie-la-dispendieuse
Transposée dans le monde de la rédaction technique, Suzie ne génère qu'une chose : REJET ! Cette documentation est coûteuse parce qu'inexploitable : aucun utilisateur ne va y trouver rapidement la réponse à sa question.  Ce faisant, Suzie a tout fait pour détruire l'image du métier et confirmer que la documentation ne sert à rien, sauf à générer des coûts inutiles !
 En cela, elle se rapproche du rédacteur de Dany Boon (celui qui explique en 5 langues comment démarrer le micro-ondes)
___________________________________________

Comment s'en sortir ? Où est l'alternative ?

Ne donner à l'utilisateur que ce dont il a besoin !... c'est la base du "Minimalism: creating information people really need"



Il s'agit d'une formation exclusivement basée  sur la _pratique_: vous apportez vos
documents et vous repartez avec VOTRE DOCUMENTATION passée au crible du minimalisme.

La documentation minimaliste ?... un mauvais plan !

La documentation dite minimaliste ne m'intéresse pas parce que :

• je n'y connais rien

• ça n'a pas été inventé chez nous

• c'est du mauvais travail. Il faut TOUT dire à l'utilisateur

• mon boss ADORE les gros manuels. Je suis payé à la page...

• le département de documentation n'a pas de problèmes de budget

• les utilisateurs ? Je m'en fiche ! Ils n'ont qu'à lire le manuel de A à Z

• il est hors de question de changer de méthode de rédaction. On a toujours fait comme ça

• vous parlez DITA ?
  
  Publication sur tablette ? Responsive design...? Foutaises ! Il n'y a qu'une seule doc, c'est la documentation papier !

• vous voulez mixer Twitter et la documentation technique ?...  Profonde aberration ! 

On ne se la joue pas "Première Dame", chez nous !

• l'overdose d'avertissements et de notes vous gène ? 

C'est inévitable, parce que l'utilisateur est un crétin !

Il faut tout lui répéter !

Pour plus d'information sur le montage d'un atelier "minimaliste", contactez [flacke@orange.fr]

Les idées fausses sur le minimalisme

Documentation figée ?

Dans un article bien détaillé, Joe Pairman reprend les points avancés par Mark Baker qui, lui, prétend que le minimalisme conduit à une documentation inerte ou figée.

La discussion se déroule sous forme de duel très, très webien qui vaut vraiment plusieurs minutes de notre attention.

Première salve : le rédacteur ajoute-t-il une quelconque valeur à la documentation ?

"When technical communicators ask how to get more respect for the profession, Baker replies with another question: In a world where
information is freely available from many sources, how can you add
most value to your organization?"

Mark Baker avance l'idée selon laquelle le minimalisme n'ajoute  aucune valeur à notre production. Pour lui, la documentation est gelée, fixée éternellement : elle n'est pas mise à jour pour tenir
compte de l'évolution du savoir-faire de l'utilisateur.

De plus, il prétend que le minimalisme ne pose pas la question du "pourquoi" et qu'il n'est question que de tâches...

A l'évidence, Mark Baker n'a pas suivi de cours sur le minimalisme et
n'a certainement pas lu le bouquin de Carroll et Hans van der Meij.

Riposte de J. Pairman : le rédacteur n'est pas un chien d'aveugle

Concernant le reproche de la documentation figée (la documentation
ne s'intéresse pas aux besoins de l'utilisateur ni à ses connaissances précédemment acquises),
J. Pairman rappelle que le minimalisme, dans son premier principe, recommande de se focaliser sur les "véritables objectifs de l'utilisateur".

Selon le minimalisme, il n'est plus question de _description_ du produit (l'utilisateur l'a devant les yeux, le produit ; il voit bien son interface).

Seul le rédacteur inexpérimenté commence par décrire les menus, les boutons, et autres futilités.

Au lieu de se mettre à la place de l'utilisateur et s'imprégner de ses besoins, il se comporte en chien d'aveugle :

"Tu vois, là, c'est le bouton OK. Dessus, c'est écrit "OK" et ca veut dire
que tu es d'accord et que tu peux valider".

Le rédacteur dûment formé aux règles du minimalisme se concentre sur les besoins et les tâches que doit accomplir l'utilisateur. Programmer le lave-vaisselle ? Préparer une opération à coeur ouvert ? Moissonner son champ ?... et bien on ne va pas lui décrire les 26 boutons du menu du lave-vaisselle, mais seulement lui donner les 2 ou 3 étapes pour programmer l'appareil. C'est tout... parce que c'est tout ce que veut savoir l'utilisateur.

C'est bien la preuve que le minimalisme tient compte des besoins de l'utilisateur et de son savoir-faire.

Le rédacteur ne va pas indiquer, sur un ton péremptoire, "il faut aiguiser la lame de la moissonneuse" (l'agriculteur le sait depuis sa première faucille), mais rédigera une section sur la procédure recommandée pour enlever les lames (avant de les aiguiser).

Infobésité : combien ca coûte ?

Le coût de l'infobésité

"Pour les entreprises, la recherche d'informations équivaut à 1855 euros par an, par employé et 95 heures de travail perdues..."

Dans cette excellente illustration du phénomène de surchage d'information, on relève également :

33 % des sondés lit quelque fois les documents reçus jusqu'à la fin...

Et cela nous concerne, en documentation utilisateur : nous nous adressons aux 67 % restants. Ceux qui n'ont pas besoin de lire les 100 % de documentation pour atteindre leur objectif : trouver la bonne procédure pour effectuer une tâche précise qui leur permettra d'atteindre cet objectif.

En panne sur l'autoroute, Charly a besoin de connaître la procédure exacte pour positionner les câbles de redémarrage et relancer le moteur. Il a déjà certaines connaissances : il sait qu'il faut distinguer les signes (+) et (-) et les brancher sur les points correspondants de la batterie. Par contre, il a besoin de précisions, sachant que la batterie se trouve sous le siège conducteur (celui qui est très très bien fixé sur le véhicule...). Il veut trouver rapidement la solution dans le manuel de bord, sachant que son objectif n'est pas d'apprendre  toutes les particularités techniques de son véhicule, mais de retrouver sa (charmante) amie au restaurant dans une heure.

L'essentiel pour Charly est donc, en ouvrant le manuel, de localiser rapidement l'information pertinente et de pouvoir s'en servir.

Et il préfèrera trouver, dans la table des matières, un titre pertinent :
 "Redémarrer la batterie"  plutôt que "Résolution de problèmes"  ou "Petites réparations".

Dans l'index, il aimerait trouver sous "B"
Batterie , charger , redémarrer, etc
et sous "C"
Charger, batterie  
Câbles, p. batterie  

Crocodile, pinces

La procédure devra être particulièrement succincte (sans longue introduction sur les principes de ré-activation de la batterie) :

Redémarrer la batterie
1. Vérifiez que le levier de vitesse est au point mort
2. Capot ouvert, placez les pinces comme indiqué dans l'illustration n° 1
3. Mettez le contact
4. Laissez tourner le moteur pendant 10 minutes
5. Débranchez tout d'abord la pince  (+)  puis la pince (-)

Pour l'entretien de votre batterie, voir chapitre XXX

On peut également s'imaginer un Guide de démarrage rapide qui ne contiendrait que l'illustration du capot ouvert et les deux points de branchement des pinces avec un titre "Redémarrer la batterie".


Et c'est ainsi que le moteur est relancé... sans infobésité !