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!

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...

Le minimalisme... mais ça vient d'où ?

Est-ce le dernier mouvement hype du XXIe siècle ? La documentation technique minimaliste deviendrait-elle "très tendance" ?...

Au risque de vous décevoir : et bien non !

Le minimalisme trouve ses origines dans les travaux de  John M. Carroll (qui n'avait pas l'honneur d'être un authentique "technical writer", lui).

Le manuel fondateur date de 1990 : "The Nurnberg Funnel - Designing Minimalist Instruction for practical Computer Skills", aux éditions du MIT

Le second ouvrage de John Carroll s'intitule "Minimalism beyond the Nurnberg Funnel",  toujours chez  MIT Press.

Effaré de constater que l'on tendait à enseigner les bonnes pratiques de la documentation utilisateur selon les mauvaises pratiques dites "de l'entonnoir de Nuremberg" ("Nurnberg funnel"), En effet, la méthode du bourrage de crâne n'a pas vraiment fait ses preuves (sauf pour l'abrutissement de l'apprenant).

Pire encore : "Carroll observed that modern users are often already familiar with much of what is described in the typical long manual. What they need is the information to solve the particular task at hand. They should be encouraged to do them with a minimum of systematic instruction."

 On notera que, pour Carroll, le fondement de la rédaction technique est bien de donner à l'utilisateur l'information dont il a besoin pour accomplir une tâche, et ceci avec un minimum d'instructions. 

Depuis le premier ouvrage de Caroll, un beau bouquet d'articles a été publié. Prenez le temps de jeter un oeil sur :

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

• What makes minimalism so popular today?

•  When is Minimalism the Best Course?

• Using Minimalism to Cut Complexity and Costs

• Minimalism and DITA enable significant Cost Savings for Avaya Telephone Manuals

• Scenarios and Minimalism

• La liste des publications du Prof. Hans van der Meij de l'Université de Twente (Pays-Bas)