Minimalist documentation is not a suitcase!

Designing minimalist documentation is increasingly in demand. In particular, due to documentation experts migrating their content to DITA.

 

Not surprising, aliens now decide to board the train of minimalism  ... and miss the step because minimalism is not a suitcase!

What is minimalism?

"Minimalism consist in identifying the smallest amount of instruction that allows for the successful completion of a task "
 
In other words, providing the minimal dose of information for the user to reach his goal.
Not cutting words, using icons or pouring safety and security measures on your website and in all of your content...

What's in this minimalist suitcase? 

• Re-use                                                                                                                                                                                                                               
  
  The suitcase owner suggests to "think about the multi-use value of a piece of information. A well-designed graphic, for example, can be useful in multiple topics." 

Unfortunately, documentation re-use does not belong to the minimalism approach. Saving documentation cost by re-using topics is the main goal of a DITA implementation.

Minimalism was developed in the late eighties by researchers in cognitive science. It focused on the USER's needs for information on performing a task.
 
DITA development started in 2001 with IBM developers looking to reduce documentation costs by re-using content. This was a business-oriented authoring perspective, not user-oriented.

You can design a "minimalist" user guide without considering content re-use!

• Universally appealing design                                            
  

The author stresses: "For documentation: always select a design and style that is universally appealing (or at least inoffensive) and will not cause problems during localization."

It would be interesting to see an example of a "universally appealing" piece of

user's documentation. 

Indeed, our colleague Ron Blicq demonstrates that publishing for the US, UK, Australia, etc

"means tackling many more differences than just changing the spelling and general terminology... Readers who encounter expressions that can be misinterpreted or simply not understood may downplay the importance of the information or comment disparagingly on the writer’s capability as a communicator."

If writing for an English-speaking (mother tongue) audience spread over several continents is challenging, how do you provide universally appealing documentation for multi-lingual audiences?

BTW, minimalism never considered localisation... although we could include it in  "helping the user to perform a task  in the user's language. "

• Layer                                                                                               

"For documentation: don’t try to dump all information onto the user at once. Layer it with techniques like DHTML, allowing the user to reveal information as needed."

Why DHTLM? How to prevent "dumping all information onto the user at once" in a paper document (i.e. without DHTML)?

Users of minimalist documentation don't need DHTML to quickly find the information they need. Thanks to a clear and precise Table Of Contents and a carefully designed Index (based on meaningful titles), they quickly find the small piece of information they are looking for.

In addition, a minimalist document increases findability (i.e. "revealing information")  because "Minimalism means [creating] small non-linear chunks readable in any order"

Minimalism authoring does not need TOOLS such as DHTML, it needs the author's BRAIN!

• Compress to icon                                                               

"Think of ways that you can compress content to get it out of the way; for example, DHTML or graphics that can compress to a small icon when clicked."

Using icons to compress content? This brings two questions:

• Does this help the user reach his objective?

No, because users hardly understand the meaning of an icon:"Most icons continue to be ambiguous to users due to their association with different meanings across various interfaces. This absence of a standard hurts the adoption of an icon over time, as users cannot rely on it having the same functionality every time it is encountered."

• Does this reduce the amount of content?

No, because icons are useless if you have to explain them.You are just adding graphics to text:"Due to the absence of a standard usage for most icons, text labels are necessary to communicate the meaning and reduce ambiguity."

Therefore, are we using icons to help users find the right information ...or just adding more confusion to the documentation?

• Critical info

The author stresses:"For documentation: make sure that your users can find the critical info, such as your company contact info, quickly. Include safety and security measures on your website and in all of your content."

Are we sure the end-user is going to look for critical info on the website ? Why do we publish paper manuals? 

Research has demonstrated that putting safety measures "in all of your content" is counterproductive. In "Warning: Superfluous Warnings Are Hazardous" Jakob Nielsen reveals:

"Most instruction manuals are littered with "important" warnings that caution against obvious stupidities, burying actual dangers amid a mass of irrelevancy .
An out-of-control legal system has made a joke of the entire warnings concept; products are now less safe because nobody bothers to read warnings anymore"

BTW, the user NEVER opens the manual to search for a warning message. He just wants an information to perform a specific task safely. He wants clear instructions. He does not want to be frightened.

 

Dancing the tango with your suitcase (one step forward, two-step backwards)

In 2013 the author explained why minimalism fails.One reason was: 

 "because [users] don’t understand big conceptual issues, such as the internal

mechanisms of the product."

Sorry, but I don't understand how my good-old-car works. This does not prevent me from driving it to a smart conference.

Mid-2015, when everybody is showing enthusiasm for minimalism, she makes a nice 180 degree turn advocating for minimalism... Dancing the tango with a suitcase?

Minimalism outside the suitcase

To pack your suitcase with effective and efficient minimalism guidance, you could start by following two (genuine) "minimalism" gurus:

John Carroll (receiving an Award at STC annual conference June 2015... time to listen to him!)

Dr. Hans van der Meij, 

keynote speaker at 

DITA Europe 2015 conference

 __________________________________________________________

Essential further reading  

• Minimalism updated 2012, JoAnn Hackos - time to check your knowledge about minimalism!
• Three new misconceptions about Minimalism ("Too Big To Know"?), Joe Pairman - time to sit down and stop "writing fluff"...

 _____________________________________________________

Getting trained in minimalism 

If you want to know more about minimalism, check these workshops and add this book to your suitcase!

 

 

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

• Workshops are available in the US and in Europe. 
• Your organization can hold an in-house workshop.(Reduced rates)
• If financing your participation to a workshop is an issue, link your management to this discussion or this one (in German). 

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

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.

________________________________________________________________________

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 poteau, Sergio, 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 !
- 

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

•  Minimalism Beyond the Nurnberg Funnel

• First Minimalist Manual 

• Minimalism principles  

Applications

• An application of the Principles of Minimalism to the Design of Human-Computer Interfaces

•  Minimalism updated 2012 

•  Minimalism and DITA enable significant cost savings for Avaya Telephone manuals

• What make minimalism so popular today?

•  Scenarios and Minimalism, by Bill Gearhart

• Minimalism: a cereal killer

•  List of references

Academic research

•  The minimalist Approach to Online Instructional Videos, by EH Pflugfelder, published in Volume 60, Number 2, May 2013 l Technical Communication

•  John Carroll's The Nurnberg Funnel and Minimalist Documentation,  by David Farkas in IEEE Transactions on Professionnal Communication, vol.33, No 4, December 1990

•  Ten misconceptions about minimalism, by Dr. Hans van der Meij 

• 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

•  Content Curation: Building bridges between web writing and DITA Authoring

• User scenarios - A Center Point for User Learning
• Structured authoring 
• Why Don't People read the manual?
• Why users don't  read that f... manual? (video)

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 ;-)

Documentation médicale:l'infobesity,ça se soigne, Docteur ?

Dans le secteur de la santé, on connaît l'importance de la documentation. C'est pour cela qu'on fournit des manuels de 500 pages destinés au personnel médical !

Les équipes de soins ont -surtout dans les hôpitaux français- le temps de s'arrêter, une

tasse de café à la main, pour lire 3 chapitres du guide utilisateur...

Et si, au lieu de leur fournir une documentation inexploitable, on cessait de dégurgiter du texte pour le plaisir (le nôtre, pas le leur...) ?

Evitons l'infobesity !

Selon Dr. JoAnn Hackos : 
 "In fact, the shorter and more lean the text, the more likely it will be read"

En clair, en documentation : ce n'est pas parce que c'est long que c'est bon !

Eliminer, dégraisser... c'est possible !

Eliminer ce qui ne sert qu'à agacer l'équipe médicale (elle a un patient à traiter et ne cherche pas, dans le manuel, ce qu'elle sait déjà), comme par exemple :

Mais bien sûr, le manipulateur radio a vécu ces 40 dernières années dans une grotte de Mongolie inférieure et ne sait pas qu'un voyant vert indique que l'appareil marche !

De  même, il n'est pas nécessaire d'expliquer, plusieurs fois, que pour sortir d'une application, il faut appuyer sur EXIT.

Tout est bon à mettre dans la documentation !

A trop vouloir tout dire, l'utile et le futile, certains rédacteurs se prennent les pieds dans le tapis.

 Ainsi, le mode d'emploi d'un défibrillateur précise, dès la page 5, qu'il faut aller vite : 
 "... les taux de survie liés aux arrêts cardiaques...sont directement liés à la rapidité d'intervention... Chaque minute de délai entraîne une diminution des chances de survie d'environ 10 %"

Bien vu, mais alors pourquoi fournir à l'utilisateur un manuel de 108 pages si l'on n'a que quelques minutes pour sauver une vie ?

Sur-irradié à cause du manuel... en anglais !

Au lieu de se concentrer sur le superflu et l'inutile, il est préférable -en matière de matériel médical- de s'impliquer dans la traduction des documentations dans la langue de l'utilisateur. Cela évitera de graves accidents.
 

Il a donc fallu plusieurs décès et des centaines de personnes mutilées pour que les autorités sanitaires rappellent aux fabricants leur obligations. 

Dans sa note d'août 2007, l'AFSSAPS  rappelle  dans son "AVIS AUX FABRICANTS DE DISPOSITIFS MEDICAUX DE RADIOTHERAPIE" , l'article R. 5211-20 du Code de la Santé Publique qui stipule que la notice qui accompagne le dispositif médical  et toute information relative à son fonctionnement doit comporter une version rédigée en français.

Il était temps... puisqu'un autre problème de sur-irradiation faisait ressortir que
  " Les appareils avaient été là aussi mal réglés car le manuel d'utilisation était en anglais. "

La norme et ses contraintes 
Trop souvent, le rédacteur oublie de penser d'abord à son utilisateur. Il préfère suivre aveuglément la norme.

Ainsi, la norme IEC 62 083 indique, dans son annexe A : "Les INSTRUCTIONS D'UTILISATION et la description technique doivent contenir toutes les informations nécessaires pour effectuer sans risque: les opérations ... d'installation, d'utilisation et de maintenance du  matériel..."

Le rédacteur distrait composera donc un beau, gros manuel -499 pages seulement- incluant une Introduction, un A propos de... (ou Aperçu), une section Généralités (dans laquelle il noiera une information capitale) puis une section Installation (surtout si le matériel est volumineux et très compliqué), suivie d'une section "Consignes de sécurité" (24 pages d'avertissements). Il abordera alors la partie "Utilisation". On sera alors à la page 189.

A ce stade, il s'apercevra qu'il manque une section "A propos de ce manuel" dans laquelle il décrira les conventions typographiques, les icônes et autres futilités.

Lorsque le manuel aura atteint la page 250, le rédacteur formé au minimalisme lui expliquera que tout cela est INUTILE et que l'utilisateur a besoin de trouver, dans la minute qui suit, une  information précise sur la mise à zéro des données du patient avant traitement... C'EST TOUT !

Et la norme ?

C'est exactement ce que dit la norme : fournir les "informations nécessaires pour effectuer sans risque les opérations d'utilisation du matériel".

La documentation ne doit contenir que ce dont l'utilisateur a besoin ; un médecin n'a pas besoin des guides d'installation (parce que c'est le fabricant qui procède à l'installation) ni du guide de maintenance (le fabricant doit s'en charger). Ou alors voulez-vous vraiment que le médecin  revienne le dimanche s'occuper de la maintenance de son scanner ?

C'est pourquoi le rédacteur qui met en avant les besoins de son utilisateur créera SEPAREMENT :

• un manuel d'installation (destiné au représentant du fabricant chargé de l'installation) 
• un manuel de maintenance pour le technicien qui vient régulièrement vérifier les paramétrages et l'usure du matériel.

La bonne blague espagnole 

Ne manquons pas cette petite histoire de documentation pharmaceutique inadaptée... celle des notices diffusées en espagnol pour le personnel médical anglophone (et en

Grande-Bretagne).

Comme le fabricant n'avait plus de notices en anglais, il a envoyé les notices en espagnol ! 

Il faut juste espérer que les hôpitaux britanniques avaient assez d'infirmières espagnoles à disposition !

C'est certainement une nouvelle version de ce que l'on appelle "parler anglais comme une vache espagnole "

Minimalisme appliqué à la documentation médicale

Pour un exemple de mise en place des principes du minimalisme pour la documentation médicale, vous pouvez suivre cette présentation faite à la Scientific Conference on Strategic Development and Performance in Healthcare Institutions en janvier 2013.