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 rappelé dans cet article inspiré par Dr JoAnn Hackos et plaçant la résolution des problèmes dans le champ du minimalisme.   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 (même si vous n’envisagez pas une migration vers DITA) !

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

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.


A lire aussi :


Documentation technique ?… Jetez un oeil sur le site AwelABen

 


Laisser un commentaire ?

Anti-spam *

ERIKSON
GSX
COHERIS
SCHLUM
EFFICIENT
OPTIS
INTERSEC
NMJ
TALEND
LYRA
HILL
HORIBA
ERIKSON
GSX
COHERIS
SCHLUM
EFFICIENT
OPTIS
INTERSEC
NMJ
TALEND
LYRA
HILL
HORIBA

logo-bleu

Établissement de formation à la documentation technique

Formatrice : Marie-Louise Flacke

Graduate of the American
University of Paris
Tel. 06 03 20 50 10

… mais que signifie Awel-A-Ben ?

Contact

BLOG

blog-icon

 

PRESS

press-icon