26/05/2015

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 meeting two (genuine) "minimalism" gurus:




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





     Hans van der Meij presenting "A closer look at instructional video" (June 3rd, Utrecht, NL) __________________________________________________________

    Essential further reading  

     _____________________________________________________

    Getting trained in minimalism 

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

     

     

    12/03/2015

    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  :



     ... Et si vous invitiez votre boss à vous accompagner à l'une de ces conférences ?

    25/02/2015

    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 :


    "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 ?

    28/01/2015

    Comment (bien) démarrer un projet de documentation ?




    Que vous optiez pour une documentation minimaliste ou plus simplement structurée, il vous faut DE-MA-RRER !

    S'asseoir devant une page blanche ou copier/coller le vieux manuel de 2001, n'est PAS la bonne solution !





    _________________________________________
    De la méthode & de la norme (ISO 26 514)!
     
    Pour envisager des processus plus efficaces et économiques, contactez-nous ! Nous pourrons organiser une présentation dans vos locaux ou dans un lieu à convenir ensemble.

     


    On y parlera 


    • définition des besoins, 
    • utilisabilité, 
    • profil utilisateur, 
    • récapitulatif des tâches, 
    • modélisation de procédure, 
    • feuille de route du rédacteur, 
    • etc.

     




     ________________________________________
    Bien démarrer en 2015 ?

    Un Guide rédactionnel ne vous dit rien ? Une procédure orientée tâches ne vous intéresse pas ?... Une Short Description vous laisse indifférent ?

    N'hésitez pas à nous en parler : un message électronique  suffit ;-)

     




    Comment bien démarrer 2015 ? 
    C'est démarrer avec les bonnes méthodes !