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

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 ?





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?


12/09/2014

What's in a minimalism workshop?


What are you going to learn in a minimalist workshop?

No, you won't cut words and you'll go on writing complete, grammatically correct sentences.

You'll learn how to provide the necessary information to your users... and, above all, you'll learn how to respect your users.

Too often, information developers forget the essential: their user has
already a lot of knowledge and experience and this should be respected.
_________________________________________________

Example 

 (excerpt from TC World magazine)
1.    What is a user account?
2.    Set up a user account
    2.1    What is a set-up assistant?
    2.2    Create new user
    2.3    This is how it works: New user

3.    What is account management
    3.1    Configure control elements
    3.2    This is how it works: Customize account management 

_________________________________________________

Analysis

CONSISTENCY

The title format is disturbing because not consistent.This mix of instruction-like ("Set-up a user account") titles with questions, combined with statements ("This is how is works...") is a challenge for the end-user.

Questions are usually grouped in a FAQ and descriptions ("This is how it works...") belong in a tutorial, while instructions are the basics of any user guide (Installation Guide, Operator's guide, Maintenance manual, etc.)

CONTENT

The content is also quite surprising. 

Differentiating between "Set up a user account" and "Create new user" (*) needs some clarification. Where is the difference?

The "minimalist writer" considers: "When Charles, the database administrator, receives a request for a new user, how does he call the task: 'Setting up a user account' or 'Creating a new user'?
 Based on that, the writer starts drafting the instructions while maintaining a consistent terminology. Synonyms should be banned from any user documentation! They disturb the user : "Why another term? Why another phrase? Do they refer to different actions?"

STRUCTURE

Interesting is also point 3.2.
It aims at providing conceptual information ("this is how it works"...), but provides _instructions_: "Customize account management". The title format is similar to point 2.2 : "Create new user".  Another example of inconsistency. If it's a procedure, give it a procedural-type title (based on an action-verb).
Usually, users are not interested in knowing how it works. They want to perform a task to reach their goal. That's all!

USER (Respecting your users)

More significant here: the documentation designer forgot an essential point. 

The user is not stupid, he is not a 6-year old in charge of managing user accounts. This is a professional with at least 3 or 4 years of experience in user account management. 
As a technical author, do you feel like explaining this IT professional what a user account is?...

In the documentation process, technical communication professionals put the user first :  they define the user's profile, his previous knowledge, his work environment, etc.  It's the best way to respect the user and it's the best way to be respected as technical writer!
_________________________________________________

Proposed (minimalist) solution


1. Setting up a user account
1.1 Setting up a user account from the XXX page
1.2 Setting up a user account with the set-up assistant
2. Managing a user account
2.1 Configuring  control elements
2.2 Customizing the account management
_________________________________________________

 DITA-compliant?



Desperate situation: following the original model, it is obvious the documentation won't be DITA-ready. It is going to be a costly and painful migration to sort (and re-write) the content in tasks, concepts and references...





_________________________________________________

More information on Minimalism workshops



_______________________________________
(*) wondering wether it's possible to create an old user account...


28/08/2014

Section "Troubleshooting" ...Comment faire ?

Un chapitre "Troubleshooting" dans ma documentation ? Reprise sur erreur avez-vous dit ?...
 
 C'est le principe n° 3  du minimalisme : "Support error recognition and recovery". Il s'agit d'aider l'utilisateur à retomber sur ses pieds, alors qu'il a fait une erreur.
Pour faciliter le retour sur la bonne voie, le rédacteur a deux options: 
  •  donner la résolution du problème exactement là où a pu se déclencher l'erreur, c'est-à-dire dans la procédure,
  • créer une section "Résoudre les problèmes".
Intervenir directement dans la procédure répond exactement à la recommandation de Dr. van der Meij : 
"Provide error information when actions are error-prone or when correction is difficult"
Ce principe de la correction d'erreur est complété par Dr. JoAnn Hackos, (webinaire du 27.08.2014). Il s'agit d'aider les utilisateurs à détecter, définir, diagnostiquer et corriger les problèmes.

L'essentiel est d'indiquer : 
  • la cause du problème
  • le moyen de résoudre le problème
A ne pas négliger non plus : donner -à l'utilisateur- la possibilité de trouver rapidement le chapitre "Troubleshooting" !



 "Troubleshooting" : le modèle______  


Le comité DITA OASIS a mis au point, dans sa version 1.3, le modèle de rubrique "Troubleshooting".  Aucune raison de ne pas s'en inspirer !

En prenant l'exemple de l'article du 3 juillet 2014 (Comité DITA OASIS), on va repérer les éléments de ladite rubrique : Title, Short Description, Condition/Situation, Cause, Remedy


Mise en pratique

 ________________________ORIGINAL____________________________
Titre: System will not turn on


ShortDesc: Everything looks right, but the system still does not start


Condition/Situation: The system is plugged in, the power switch is on, but the system will not start.


Cause: The problem is usually due to power not being supplied to the system through the electrical outlet. Often, a circuit breaker has been tripped so that no power is available at the outlet.


Remedy/Solution
WARNING
If you don't not know how to reset circuit breakers, do not attempt ot fix this problem. Instead, find somebody who is qualified to do this for you.

1. Turn the system power switch to OFF
2. Reset  the breaker
3. Turn the system power switch on O
N.

The system turns on.

_______________________
VERSION OPTIMISEE______________________
On peut optimiser le contenu, tout en gardant la structure :

Titre : System will not start

Mini Desc : If the system does not start, it is probably due to the circuit breaker. It is recommended to have a qualified professional reset the circuit breaker.

Situation : The system is plugged in, the power switch is on, but the system will not start.

Cause : Power is not supplied to the system through the electrical outlet. A circuit breaker has probably been tripped that blocks power distribution.


Solution :
1. Make sure you have the necessary skills to reset the circuit breakers

2. Turn the system power switch to OFF
3. Reset  the breaker
3. Turn the system power switch on ON.



______________________

COMMENTAIRES

  •   En anglais, nous avons l'élément "Condition" qui, IMHO, peut porter, en français, à confusion. On serait tenté par une traduction littérale et cela mènerait inévitablement à de grosses bourdes. Il ne s'agit pas de donner les conditions pour que le système ne marche pas, mais bien de clarifier la SITUATION de blocage dans laquelle l'utilisateur se trouve.
  •  La version originale inclut un "Warning" qui s'avère inapproprié. Il n'y a pas de danger physique (ou, tout au moins, il n'est pas indiqué), donc pas d"AVERTISSEMENT". 
Rajouter des avertissements dans une rubrique "Troubleshooting" va mener vers le sac de noeuds dans lequel l'utilisateur ne retrouvera pas les instructions nécessaires à sa reprise sur erreur. 
L'information contenue dans cet avertissement peut trouver sa place dans une instruction et, comme démontré ci-dessus, dans la "Short Description".

Chaque rubrique  "Résolution des problèmes" s'insère  fort bien dans un chapitre "Résoudre les problèmes" qui, avec un titre parlant, facilite la recherche.

L'insertion d'une mini-rubrique "Problème ?" dans la procédure, sera détaillée dans un autre article du blog...

_____________________________________________________

Poursuivre l'exercice ?

Venez en parler lors de la conférence User Assistance Europe qui se tiendra les 9 et 10 juin 2016 à Budapest où il sera question de... troubleshooting !



24/06/2014

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 :









  • 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, 1928nous 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.



    Minimalist documentation : is this workshop for you?


    • Is your management asking you to reduce documentation costs? 
    • Do you create information that few customers use? 
    • Do you have fewer people to create and maintain the volume of information you've created in the past? 
    • Are you pursuing content management and structured writing?
    ______________________________________________________________________
    Attending a "minimalism" workshop          
    If your answers are "yes,"a minimalism workshop meets your needs directly. Minimalist documents take time and effort to design, but once you have them in place, the savings are clear. Minimalist documents cost less to produce, are easier to maintain, and reduce requests for customer support.

    ________________________________________________________________________  Minimizing your production costs

    Minimalism is the key to getting the maximum return on your single-sourcing investment.



    Minimalism isn't only for simple products or targeted at beginners. A minimalist approach makes complex products easier to understand and gets critical information more directly into the hands of experts.

    People attending this workshop report they've reduced their documentation by 50 to 75 percent.


    _______________________________________________________________
    Taking your documentation to the mobile world

    Is your documentation going mobile? Did you know that Mobile content is twice as difficult ?

    Minimalism is designed for your needs (or do you
    want to copy-paste your PDF manual on your mobile screen?...) 


    _________________________________________
    Workshop: Is it really for me ?
    This workshop offers a hands-on approach: You work on your own documents for more than 50 percent of class time. Be sure to bring a sample of past work, work-in-progress, or planned work that you want to trim. If you have a team working on reducing document size and cost, we recommend coming to the workshop together.

    You will learn to:
    •     Evaluate when minimalist strategies should be used
    •     Know the four basic principles of minimalism
    •     Understand why you must motivate users
    •     Promote learning by doing rather than by reading
    •     Evaluate what to trim and why
    •     Focus on troubleshooting advice
    •     Identify opportunities to replace text with graphics
    •     Get maximum value from graphics
    •     Write, edit, and review documents for minimizing
    •     Prioritize your efforts when resources are slim
    After the 29-30 september 2014 in Liège-Seraing, the next workshop will take place 15-16 December 2014, in Paris (in French).


    Too expensive this 2-day workshop?
    Listen to Betty discussing with her documentation manager the opportunity to register for the next workshop.
     ________________________________________________________________________

     Why is minimalism so popular today?

    People prefer that information be in the context of their goals, their tasks, and their working environment. If they can find information that directly tells them how to reach their goals, they are much happier than if they have to extrapolate from disparate facts. They would like to have information that presents them with realistic scenarios and shows how the goals of the scenarios are best accomplished. They prefer hints, tips, and tricks that show them the best way to get a task done.


    ________________________________________________________________________

    07/06/2014

    Minimalisme: principe n° 2 "L'outil intégré dans la tâche"

    Oui, mais, ... qu'est-ce que cela veut dire au moment de la conception de la documentation ?


    Anchor the tool in the task domain

    Disons : "l'outil doit être considéré par rapport à la tâche"
    Dr. Hans van der Meij nous l'explique : 
    • For most users, an application is a tool they want to use to achieve objectives in their own task domain. 
    • The tool is merely a means; it is almost never an end in itself. 
    • The designer should therefore select or design instructional activities that are real tasks.

    Les vraies tâches : comment les approcher ?

    Il s'agit, entre autre, de prendre en compte l'utilisateur (et non pas l'outil) avec :

    • son environnement de travail / ses conditions de travail 
    • son savoir-faire / sa formation initiale et continue 
    ________________________________________

    Sergio, le monteur

    Par exemple, Sergio,expert monteur de lignes électriques, aimerait beaucoup que la documentation fournie pour les nouveaux boîtiers de raccordement soit adaptée à
    son savoir-faire existant, mais aussi à ses conditions de travail.

    Pour cela,  le rédacteur prend soin de fournir un plan détaillé des circuits des boîtiers, convaincu que cette illustration sera utile au monteur.
    Pour que ce soit clair, il le fait imprimer au format A3, le tout bien plié dans le manuel papier au format A4. Beau travail.

    Au moment de grimper au poteauSergio, de son côté,vérifie son équipement : vêtements de protection, chaussures de sécurité, casque, gants de protection, harnais, outillage et
    "grimpettes".

    Question : où va-t-il maintenant glisser le manuel d'installation? 
    Ingénieux, Sergio, vient de trouver une place dans une poche externe du pantalon.

    Et c'est parti pour l'ascension avec grimpettes !

    ________________________________________

    Le rédacteur a pensé à tout... sauf à l'essentiel

     Environnement de travail

    En équilibre sur son poteau, Sergio veut vérifier un détail du montage du boîtier. 

    • Comment atteindre l'information pertinente si son environnement de travail joue les trouble-fêtes ? 
    • Comment déplier le schéma de montage au format A3 par grand vent, sous la pluie, ... ou parce qu'il doit impérativement porter des gants ?
    Retour à la case départ : le manuel est inutilisable dans les véritables conditions de travail.

    Savoir-faire : formation initiale, formation continue

    Mais, fichtre, pourquoi est-ce que l'installateur ne lit pas le manuel si bien ciselé pour lui ?


    Et bien tout simplement parce qu'il se base sur son savoir-faire. Ce n'est pas dans VOTRE manuel qu'il apprend le métier. C'est au moment de sa formation initiale.

    Ensuite, il conforte son savoir par transmission par les "anciens". Dans le cas de Sergio, ils sont toujours deux monteurs pour une installation. La transmission de savoir se fait donc sans intermédiaire et in situ.

    Donc, il n'est pas nécessaire de lui expliquer les dangers de l'électricité à haute tension ! Il le sait mieux que le rédacteur et depuis son premier cours !

    En formation continue, nombreuses entreprises chargés de travaux dangereux organisent des réunions régulières  avec tous les opérateurs pour analyser une ou deux procédures  du manuel.
    _____________________________________________________
    Alors que faire ? 
    Le rédacteur doit-il tout simplement abandonner le traditionnel "Guide d'installation" 
    inutilisable en situation réelle ?

    Non, il optera plutôt pour un manuel basé sur le minimalisme en :
    • prévoyant des fiches cartonnées pour les infos indispensables
    • envisageant la migration des fiches sur support mobile  
    • proposant des supports de formation continue (gamification, bandes dessinées, videos, etc.


    ... et en évitant de démarrer une section du manuel par "1ère étape - coupez le courant". Sergio le sait depuis longtemps !

    28/05/2014

    Minimalism authoring: some resources


    The essence of the minimalist approach is to obstruct as little as possible the learner’s selfinitiated efforts to find meaning in the activities of learning.” (John M. Carroll)


    Basics by John M. Carroll and Hans van der Meij


    Applications




    Academic research

    •  The minimalist Approach to Online Instructional Videos, by EH Pflugfelder, published in Volume 60, Number 2, May 2013 l Technical Communication
    • Applying Minimalist Principles, Strategies, and Techniques, by Susan M.J. Lester

    • Goal-orientation, goal setting and goal-driven behavior in (minimalist) user instructions,  by  Dr. Hans van der Meij, IEEE Transactions on Professional Communications, 50 (4) 295-205


    Complementary reading


    Se former aux techniques du minimalisme 

    Le prochain atelier "documentation minimaliste" aura lieu les 29 et 30 septembre 2014 à Liège. Qu'on se le dise ;-)


    26/05/2014

    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]