12/09/2014

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



_______________________________________
(*) wondering wether it's possible to create an old user account...


28/08/2014

Section "Troubleshooting" ...Comment faire ?

Un chapitre "Troubleshooting" dans ma documentation ? Reprise sur erreur avez-vous dit ?...
 
 C'est le principe n° 3  du minimalisme : "Support error recognition and recovery". Il s'agit d'aider l'utilisateur à retomber sur ses pieds, alors qu'il a fait une erreur.
Pour faciliter le retour sur la bonne voie, le rédacteur a deux options: 
  •  donner la résolution du problème exactement là où a pu se déclencher l'erreur, c'est-à-dire dans la procédure,
  • créer une section "Résoudre les problèmes".
Intervenir directement dans la procédure répond exactement à la recommandation de Dr. van der Meij : 
"Provide error information when actions are error-prone or when correction is difficult"
Ce principe de la correction d'erreur est complété par Dr. JoAnn Hackos, (webinaire du 27.08.2014). Il s'agit d'aider les utilisateurs à détecter, définir, diagnostiquer et corriger les problèmes.

L'essentiel est d'indiquer : 
  • la cause du problème
  • le moyen de résoudre le problème
A ne pas négliger non plus : donner -à l'utilisateur- la possibilité de trouver rapidement le chapitre "Troubleshooting" !



 "Troubleshooting" : le modèle________  


Le comité DITA OASIS a mis au point, dans sa version 1.3, le modèle de rubrique "Troubleshooting".  Aucune raison de ne pas s'en inspirer !

En prenant l'exemple de l'article du 3 juillet 2014 (Comité DITA OASIS), on va repérer les éléments de ladite rubrique : Title, Short Description, Condition/Situation, Cause, Remedy


Mise en pratique

 ________________________ORIGINAL____________________________
Titre: System will not turn on


ShortDesc: Everything looks right, but the system still does not start


Condition/Situation: The system is plugged in, the power switch is on, but the system will not start.


Cause: The problem is usually due to power not being supplied to the system through the electrical outlet. Often, a circuit breaker has been tripped so that no power is available at the outlet.


Remedy/Solution
WARNING
If you don't not know how to reset circuit breakers, do not attempt ot fix this problem. Instead, find somebody who is qualified to do this for you.

1. Turn the system power switch to OFF
2. Reset  the breaker
3. Turn the system power switch on O
N.

The system turns on.

_______________________
VERSION OPTIMISEE________________________
On peut optimiser le contenu, tout en gardant la structure :

Titre : System will not start

Mini Desc : If the system does not start, it is probably due to the circuit breaker. It is recommended to have a qualified professional reset the circuit breaker.

Situation : The system is plugged in, the power switch is on, but the system will not start.

Cause : Power is not supplied to the system through the electrical outlet. A circuit breaker has probably been tripped that blocks power distribution.


Solution :
1. Make sure you have the necessary skills to reset the circuit breakers

2. Turn the system power switch to OFF
3. Reset  the breaker
3. Turn the system power switch on ON.



______________________

COMMENTAIRES

  •   En anglais, nous avons l'élément "Condition" qui, IMHO, peut porter, en français, à confusion. On serait tenté par une traduction littérale et cela mènerait inévitablement à de grosses bourdes. Il ne s'agit pas de donner les conditions pour que le système ne marche pas, mais bien de clarifier la SITUATION de blocage dans laquelle l'utilisateur se trouve.
  •  La version originale inclut un "Warning" qui s'avère inapproprié. Il n'y a pas de danger physique (ou, tout au moins, il n'est pas indiqué), donc pas d"AVERTISSEMENT". 
Rajouter des avertissements dans une rubrique "Troubleshooting" va mener vers le sac de noeuds dans lequel l'utilisateur ne retrouvera pas les instructions nécessaires à sa reprise sur erreur. 
L'information contenue dans cet avertissement peut trouver sa place dans une instruction et, comme démontré ci-dessus, dans la "Short Description".

Chaque rubrique  "Résolution des problèmes" s'insère  fort bien dans un chapitre "Résoudre les problèmes" qui, avec un titre parlant, facilite la recherche.

L'insertion d'une mini-rubrique "Problème ?" dans la procédure, sera détaillée dans un autre article du blog...

__________________________________________________________

Poursuivre l'exercice ?

Venez en parler lors d'un prochain atelier  "Minimalisme : Créer l'information dont on a vraiment besoin" !



24/06/2014

Combien d'argent ai-je jeté par les fenêtres aujourd'hui ?

En matière de documentation produits, voici trois pistes pour brasser de l'air et dépenser à tour de bras :








  • passer 4 h 45 à rédiger le chapitre "Généralités" ... que l'utilisateur ne va pas lire.

  • ____________________________________________
    Suzie-la-Terreur
    Et voici Suzie-La-Terreur (terreur des équipes de rédaction) pour qui la documentation
    technique, c'est comme l'oie que l'on promène dans les rues de New York : décalée, rutilante, humoristique, hors contexte, futile... risible !

    Son manuel sur papier glacé est futile, décalé, risible et inutile parce qu'il ne répond pas aux questions précises telle que "comment faire pour modifier les paramètres sans perdre mes enregistrements précédents" que se pose l'utilisateur.

    Par contre, ledit manuel se contente de ressasser les évidences. Sous Software Update, il est effectivement impératif d'ajouter qu'il faut avoir installé la version précédente avant de mettre à jour !



    Aucune raison  de se pavaner dans les salles de réunion avec le manuel de 450 pages  si l'utilisateur s'en sert comme rehausseur de siège !

    Bien sûr, Suzie-et-son-oie-à-New-York (Photo de Ruth Jacobi, 1928nous plaisent beaucoup  : elles feraient un excellent fond d'écran . 
    _____________________________________________
    Suzie-la-dispendieuse
    Transposée dans le monde de la rédaction technique, Suzie ne génère qu'une chose : REJET ! Cette documentation est coûteuse parce qu'inexploitable : aucun utilisateur ne va y trouver rapidement la réponse à sa question.  Ce faisant, Suzie a tout fait pour détruire l'image du métier et confirmer que la documentation ne sert à rien, sauf à générer des coûts inutiles !
     En cela, elle se rapproche du rédacteur de Dany Boon (celui qui explique en 5 langues comment démarrer le micro-ondes)
    ___________________________________________

    Comment s'en sortir ? Où est l'alternative ?

    Ne donner à l'utilisateur que ce dont il a besoin !... c'est la base du "Minimalism: creating information people really need"

    Il s'agit d'une formation exclusivement basée sur la _pratique_: vous apportez vos
    documents et vous repartez avec VOTRE DOCUMENTATION passée au crible du minimalisme.

    Le prochain Atelier (en anglais) "Minimalist documentation" aura lieu les 29 et 30 septembre 2014 à Liège - Seraing (Belgique)...l'oie de Suzie-la-Terreur vous y attend ;-)