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!

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?

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.

________________________________________________________________________

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