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

    keynote speaker at 
    DITA Europe 2015 conference


    Essential further reading  


    Getting trained in minimalism 

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



    3 commentaires:

    1. It seems the author is experencing some problems with minimalism...in 2012, at the TC UK Conference, she declared:
      "#7: Layer Levels
      Minimalist documentation can be very frustrating, because it assumes that everyone needs the lack of detail. Also, stating the blatantly obvious in a step ("enter your name in the Name field") is a waste of time."
      (see http://www.writersua.com/articles/tentips/)

      At that point, it's no longer dancing a tango, but a very quick waltz...

    2. I particularly like this reminder "Minimalism consist in identifying the smallest amount of instruction that allows for the successful completion of a task". This is an excerpt from...a book? Who is the author?

    3. The specific statement in the DITA 1.0 Architectural Specification that attempts to tie DITA to minimalism ... is as follows:

      "Topic-oriented authoring for conceptual and task information has its roots in Minimalism, an instructional design technique first espoused by John Carroll. The minimalist approach to information design focuses on identifying the smallest amount of instruction that allows for the successful completion of a task, or that provides basic knowledge of a concept. Readers have goals, and they want to achieve those goals as quickly as possible. Generally, readers don’t want to read information just for the pleasure of reading. They are reading to learn or to do something."