Mr Agile cooperating with Ms minimalism...

Are you planning to join an "Agile" team of developers? Any idea about the challenges when dealing with "Sprint", "User stories", "Scrum" ? 
Our colleague Paul Coinaud -experienced "agile" technical author- agreed to share his know-how with us.

Let me tell you a (user) story...

Content management professionals’ daily activities are often constrained by the rythm imposed by engineers. This is particularly true when working with software developers. 

Technical writers are "fed" with new features and the flow of delivery is not always very regular, especially when working with several development teams simultaneously. If several projects are released at the same time, you will clearly need to deal with a peak of work. This can also be variable due to the fact that some features require a lot of content to be created, while others require none.

Since the arrival of Agile in Development teams, in particular the Scrum methodology, the rythm is much more regular as the product functionalities are delivered drop by drop, following what we call sprints.

SPRINT?... something for technical writers?

Here is how a sprint is sequenced. The Product Owner makes a list of User Stories (basically features) and prioritizes them in a backlog. A sprint planning allows dev teams to evaluate and implement the selected stories depending on their working capacity during the next Sprint (for example 3 weeks of sprint). So a set of stories is chosen and the devs will focus their work on these particular tasks.

Every day, the devs meet in front of the sprint whiteboard for a stand up meeting called

Scrum – whence the name, to see the progression and raise any potential issue. The Technical Writers can be part of the Scrum to show the team their progression or to raise any issue related to the product or the content.
   
At the end of the sprint, the feature is normally shippable and the related technical documentation should also be ready at this stage. This means the tech writers really work hand in hand with the dev team and their work needs to be synchronized as much as possible to ship a product with a decent documentation on time.

So as the sprint goes, the documentation must follow the progression. 
This gives the techwriters a well-defined working environment, with concrete tasks to perform and clear deadlines.

So let's say it, a little bit of pressure, but we all like to work under pressure, right?

SPRINT and minimalism?

Of course the Minimalist approach is an evidence here. When creating content with short deadlines, you need to focus on two things:

-    As soon as possible during the sprint, tech writers need to work with the devs to make sure the quality of the User Interface is good enough: improve the error messages, correct

mistakes in the labels (geeks love typos!) and if possible, improve the ergonomics as well. A structured product with clear error messages is reducing the probability for the user to require assistance. Plus, it will also be easier and faster to create content around this.

-    Create the information people really need:

• Focus on task oriented content, procedures that will help users accomplish their tasks. 
• Don’t forget to respect the users' level of expertise    
• If you feel like a beginner will need more contextual information before going on with tasks, add a little bit of conceptual information here. A drop.

   
Not only Minimalism and Agile principles are compatible, but if you need to create technical content, it will definitely help you focus on what matters for the end users: task-oriented content, quality user interfaces and helpful error messages with an easy access to the related help topics. 

All this combined with regular feature deliveries is the key to content management success in a software company!

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!

 

 

Le boss qui dit NON (formation continue)

Parfois les managers, chefs de projets, directeurs, "Head of..." manquent d'arguments pour refuser, aux membres de leur équipe,  une formation/une participation à un congrès professionnel, à un salon.

On peut les aider. Voici cinq arguments...

__________________________________ 1. Manque de temps 

"On n'a pas le temps, on doit livrer 2 manuels à la fin du mois"

_________________________________________
2. Manque de budget
"La situation économique est telle que nous avons d'autres priorités"

[par exemple, produire de la documentation que personne ne lit]

•  Avez-vous seulement jeté un oeil sur le budget "formation" de votre entreprise ?
•   Savez-vous que votre entreprise COTISE déjà auprès des organismes de collecte (OPCA) ?  Les fonds sont DEJA verses. Qui va maintenant les utiliser ?

 __________________________________

3. Manque de programme de formation
"On n'a pas de programme, donc on ne fait rien"

 

• ... mais vous avez une obligation de formation vis-à-vis de vos salariés (loi de Mars 2014). Vous devez leur offrir une possibilité de formation tous les deux ans, sinon vous êtes passible d'une amende

___________________________________ 4. Manque d'agrément comptable
"Pour financer un déplacement du salarié à un congrès, je vais essuyer un refus de la compta. Pas question de m'engager sur ce terrain-là"

• Savez-vous seulement qu'il existe, dans le plan comptable, un compte 625 - Déplacements, missions ? Il n'est pas nécessaire de réserver ce compte aux dépenses somptuaires des cadres supérieurs se rendant à leur congrès aux Maldives.

___________________________________
5. Le pouvoir de dire NON

C'est ce qui fait un vrai boss : utiliser son pouvoir de dire NON ! Ca le distingue de la valetaille (qui, elle, doit toujours acquiescer).

______________________________________
Calendrier
Les prochaines réunions, conférences, congrès professionnels sont d'excellentes occasions de maintenir à flot ses compétences en documentation technique  :

• Atelier "Documentation minimaliste" Outre-Atlantique
• Master Class "Minimalist authoring" à Paris le 7 septembre

 ... Et si vous invitiez votre boss à vous accompagner à l'un de ces ateliers ?

Minimalisme : A la recherche de l'info perdue...

Le 4e principe du minimalisme nous recommande  "Support reading to do, study and locate". On s'arrêtera sur la phase "localiser/trouver" (l'information pertinente).
 

Trouver rapidement l'info exacte 

Prenez Alcibiade, principal rédacteur chez SnowDamm, fabricant de canons à neige, qui a terminé "son" manuel opérateur. 350 pages, mise en page très carrée, formatage de première classe et délais maintenus à 100%.

Grande satisfaction... et, subitement, la Tuile !
 
Accident corporel autour d'un des canons à neige : l'opérateur a la main coupée. S'ensuit la réclamation du client : c'est de la faute du matériel (et du manuel).

Chez SnowDamm, c'est l'alerte au niveau du management : a-t-on bien mentionné, dans la documentation, comment graisser les disques XYZ-23 ?

Sueurs froides chez le rédacteur : "euhhh, oui,... Anastase, l'ingénieur, m'en avait parlé, donc je l'ai mis dans la doc !"

"Oh, Alcibiade ! apportez-moi la preuve. La documentation, sur mon bureau ! Tout de suite ! On court au procès ici ! Dépêchez-vous !" s'énerve le boss.

OUF ! Le rédacteur avait bien mentionné la manip' pour graisser correctement les disques. Alcibiade est un homme tranquille !

Après examen, manque de chance : la procédure n'en était pas une et, surtout, elle était difficilement décelable par l'opérateur.

En effet, bien cachée dans une note de bas de page, en fin de section "Catégorie d'huile de graissage pour le canon SnowDamm", on déniche l'information :

"NOTE : Une optimisation de la phase de graissage pour le disque XYZ-23 est obtenue en débranchant la machine après avoir enclenché le mode "REVERSE"

Rien sur "Assurer la maintenance des disques"  ou "Effectuer le graissage des disques".

Quels sont les risques à ce stade ?

Importants...! En effet, au moment du procès, l'entreprise devra répondre aux questions "qu'avez-vous fait pour éviter l'accident ?" ou "Donnez-nous la procédure précisant les conditions d'un graissage sécurisé ?"

Et là, la note mal torchée et bien cachée ne suffit pas !

La juriste et la doc

En effet, Laura, jeune juriste très efficace, attire notre attention sur cet arrêt de la Cour d'Appel de Versailles, du 20 mai 2005, faisant intervenir l'UFC-Que Choisir et la Sté Totalgaz. La Cour a jugé abusive la clause par laquelle l'utilisateur reconnaissait avoir reçu communication des notices de sécurité, non seulement en raison de son impression en caractères peu lisibles, mais aussi de son emplacement, au milieu des conditions générales. 


Et là, la jurisprudence tranche : l'info est bien là, mais difficilement accessible, donc inefficace et inutile, c'est-à-dire inexistante.

Fictive cette histoire ? ... 

Que nenni ! Regardez  cet extrait du rapport de l'accident ferroviaire de Brétigny. Le Bureau Enquete Accidents, BEA, a demandé à la SNCF de clarifier -dans la documentation- les règles de maintenance des éléments boulonnés, parce que :

"Pour trouver la norme de serrage qu'applique la SNCF à un boulon, il nous a fallu éplucher des dizaines et des dizaines de pages" 

Ainsi donc, il y aurait un lien entre un accident grave et des difficultés à trouver l'information dans la documentation. Délicat, n'est-il pas ?

Recherche infructueuse, cible manquée

In fine, rappelons-nous les propos de notre éminent confrère Michael Priesley (un des grands noms dans l'implémentation DITA) : "On-site search engines fail 70% of the time".

De même, dans un article de la revue "Best Practices" de juin 2014, Dr. JoAnn Hackos

indique "43 percent... said that they have so many overlapping versions of their content that customers cannot find the information they are looking for"

Ce qui signifie que, dans 43 % des cas, les rédacteurs ont manqué leur cible. Pour les utilisateurs, l'information fournie n'existe pas ...

On essaie d'y remédier ?