22/11/2014

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 du prochain atelier de formation "Créer l'information dont on a vraiment besoin". 

Il se déroule les 15 et 16 décembre 2014 en région parisienne, chez nos collègues de NMJ Services.

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

26/10/2014

Utiliser mon DIF pour un atelier "Documentation minimaliste" ?

 ... Non, mais et puis quoi encore ?

  _______________________________________

Quel contenu ?

  • Au cours de l'atelier, vous vous familiarisez avec les 4 principes du minimalisme, puis vous les mettez en application à partir de VOTRE documentation. Vous pouvez repartir avec vos propres documents retravaillés !
_______________________________________

 Quels destinataires ?

  • L'atelier est destiné à tout rédacteur/manager vraiment désireux de fournir (enfin !) l'information utile (... et peut-être cesser d'être la risée des utilisateurs qui n'aiment pas qu'on les prenne pour des handicapés du bulbe !)
_______________________________________

Quelle difficulté ?



Par exemple, que couvre le principe numéro 2 ("Anchor the tool in the task domain") ?

  • Le minimalisme a été développé par des professionnels de l'analyse du comportement des utilisateurs. En atelier, nous clarifions et mettons en application le résultat de cette analyse.
_______________________________________

 Quelle finalité ?

_______________________________________

 Que rejeter ?


Eliminer ? Ciel ! Est-ce vraiment nécessaire ?
  • L'utilisateur n'a pas besoin de trouver, dans un manuel, ce qu'il sait déjà : que sa tondeuse sert à couper le gazon et qu'une lame bien acérée peut couper un doigt de pied !


  • Un Ch'ti est-il vraiment capable de démontrer la pertinence du minimalisme ? 
_______________________________________

 Où s'informer ?

  • Si une information vous manque, n'hésitez pas à contacter [flacke [at] orange.fr]
_______________________________________

 Quels coûts ?

95 heures de travail perdues par employé et par an...
  _______________________________________

 Quels commentaires ?

  • Oui, mais, qu'en pensent les participants ?




______________________________________

 A quand le prochain ?

06/10/2014

Minimalism vs. Information Mapping: what's the best choice ?

Back to the sources

In an article dated April 2008, Bob Doyle provides a quasi-exhaustive recap about
 the different methods of document design.
 
Information Mapping (R) was developed in mid-60's by Robert Horn who identified 7 common"Information types" of a structured document:

  • classification, concept, principle, procedure, process, structure, and fact.

  

Structured authoring

Information Mapping is considered the birth of Structured Writing as Mike West explains in "Structured writing, structured documentation".

Information Mapping is a set of tools:
"Structured documentation is a way of planning and implementing the various phases of a writing project; and we may think of structured writing as a set of tools and techniques to be used by writers during the writing phase of a project"
If Information Mapping is the toolbox, what is minimalism?

Minimalism ?

Information Mapping(R) was designed to help engineers document their programming work (reports, descriptions, etc.). Let's say it's a writing guidance for non technical writers. Its structure is pretty rigid and not really designed for task-oriented activities; it is more a classification of information.

Minimalism was developed in the late '80s by John M. Carroll, member of an IBM team:
"It was task orientation carried to an extreme. Minimalism meant small non-linear chunks readable in any order. It emphasized reading To Do, not reading To Know or To Learn, a phrase first introduced by Ginny Redish"

Minimalism puts the END_USER in the center of the information development, not the writer. It focuses on the user's tasks. The minimalist writer ignores writing tools, GUI or product description. His first questions are always:

"Who is the end-user? What does he want to achieve with this product?"

Outdated?

Dr. JoAnn Hackos, expert both in Information Mapping (IM) and minimalism, published an interesting research article showing that 
"IM formatting makes absolutely no difference in user performance. It adds unnecessary words like the stem sentences: "Do we need all that glue?"
and considers "Information Mapping is outdated".

What is GLUE?

"Glue text is defined as transitional information intended to inform readers of what has come before or comes after a particular procedure, description, or explanation.
In topic-oriented authoring, which forms the basis for the DITA Model, transitional text has become problematic." (Dr. JoAnn Hackos)

So what ?


Talking of modular, DITA-ready documentation,  professional technical writers don't need to think about facts, principles, structure, etc.  In 2014, they focus on providing user-centered, useful and responsive documentation. The new challenges are findability and usability on Any device, anytime, anywhere... Do you really need a 4-paragraph Introduction on your Google Glass?

The next Minimalism workshops takes place in December 2014 (in English)
A workshop in French is being scheduled December 15-16 in Paris. Registration details coming very soon!