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



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




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

    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
    The next workshop is scheduled 29-30 september 2014 at the heart of Europe, in Liège-Seraing, at the crossroads between Belgium, the Netherlands and Germany. 

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

    To register to the Liège-Seraing workshop 

    click the + sign  bottom right 

    ________________________________________________________________________