Affichage des articles dont le libellé est rédaction technique. Afficher tous les articles
Affichage des articles dont le libellé est rédaction technique. Afficher tous les articles

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 de la conférence User Assistance Europe qui se tiendra les 9 et 10 juin 2016 à Budapest où il sera question de... troubleshooting !



21/05/2014

Minimalisme ? pas chez nous !

"Nous fournissons un travail sérieux, nous ! Nous ne rechignons pas devant l'ampleur de la tâche : nous fournissons la totalité de l'information ! Un travail vraiment complet... sinon rien !

Le minimalisme est réservé aux rédacteurs à mi-temps, ceux qui veulent un travail "quick and dirty" !


Alors, vous préférez l'infobésité ? 

...disons un beau manuel de 800 pages ?

Mais vous, cher rédacteur, quand avez-vous ouvert et utilisé un manuel de 800 pages ?

Rappelez-vous l'excellent sketch de Dany Boon qui tente de lire -en première mondiale- un manuel utilisateur en entier ...


Complète votre documentation ?

 ... mais est-elle utile ?
Effectivement, 400 pages seulement pour votre guide opérateur paraissent bien digestes. C'est bien ! Mais savez-vous comment votre utilisateur va chercher (et trouver) l'information qu'il recherche ? 

Avez-vous remarqué que Nokia produit la totalité de sa documentation selon les 4 principes du minimalisme ?

...à votre avis, vos utilisateurs ne méritent pas la qualité Nokia ?

 Secteur réglementé

Vous rejetez le minimalisme parce que vous intervenez dans le nucléaire ? dans le médical ? dans l'aéronautique ? ... Vous souvenez-vous QUI vous a démontré que les règles du minimalisme étaient incompatibles avec votre secteur ?


Branchez-vous sur l'enregistrement du  webinaire organisé par la STC France le mardi 27 mai 2014 ! Vous aurez la présentation et les échanges.


Formation par atelier interactif

Le prochain atelier aura lieu les 29 et 30 septembre 2014 à Liège (BE)



03/05/2014

Grammaire, conjugaison, phraséologie... Quel ennui !

Dans un raccourci fulgurant, certains rédacteurs pensent qu'en implémentant les règles du minimalisme, ils peuvent passer rapidement sur ces scories que sont les règles de
grammaire, de conjugaison et autre horreurs comme l'orthographe.


Puisque le minimalisme cherche à éliminer le superflu, éliminons les rigidités grammaticales !


 La conjugaison ? quelle abomination !

Et pourtant, parmi les principes de base de la rédaction "minimaliste", on trouve :  "Rédiger au présent" (jamais au futur). 
En effet, l'utilisateur veut savoir ce qui va se passer s'il appuie sur ce bouton vert MAINTENANT, pas dans 30 minutes.
  • Appuyez sur CRTL+ALT+XXX                                                                      L'enregistrement démarre. 
        (et non pas "L'enregistrement va démarrer" ou "L'enregistrement démarrera")

Dans une présentation disponible en ligne, notre collègue Sharon B.  recommande, dans sa diapo n° 25, de rédiger à la voix active et au temps présent.

Dans sa colonne de droite, elle indique donc "Present tense" et donne des exemples dont :

 "Your email is automatically sent the next time a network is found"


... oui, un abysse s'ouvre devant nous  !

Si cette phrase est au présent (et accessoirement à la voix active), je veux bien être condamnée à nettoyer la place de la Concorde à la brosse à dents !

Dans les temps antédiluviens, on faisait la différence entre le présent et le passé composé : "Votre e-mail est envoyé automatiquement dès que le système trouve un réseau" (passé composé)
-et-
"Le logiciel envoie votre e-mail" c'est du présent (et de la voie active).

Pour les hésitations en conjugaison, voici de quoi vous rattraper aux branches...

Voix passive ...quelle dérive !

Tous nos grands maîtres en documentation technique s'accordent pour nous recommander : "N'écrivez jamais à la voix passive". Tout simplement parce qu'on ne sait jamais, dans ce cas, QUI fait l'action.


Comme par exemple :
"Le logiciel est démarré en appuyant sur le bouton"   -ou- "L'alarme est neutralisée après le déclenchement du levier vert".

D'accord, mais qui appuie sur le bouton ? le perroquet ? la musaraigne qui passait par là ? ou alors est-ce que le logiciel est programmé pour déclencher un appui sur le bouton ?

De mauvaises langues rapportent que, lorsque certains rédacteurs tournent leurs phrases au passif, c'est parce qu'ils n'ont pas compris le fonctionnement du système (et ne veulent pas trop se fatiguer à chercher)... des mauvaises langues, je vous le dis ! 
 

En minimalisme, une seule voix : la VOIX ACTIVE !

                  Dès que vous appuyez sur le bouton XXX, le logiciel démarre
Malheureusement, notre collègue californienne n'a pas été touchée par la grâce de la voix active (vu qu'elle ne fait pas la différence entre les deux voix...)







Allons, l'essentiel est que la collègue Sharon B. puisse continuer à organiser ses séminaires, ses brassages d'air et son "manque-pas-d'air" (voir ses commentaires, sous sa présentation Slideshare, lorsqu'on lui fait remarquer ses dérapages...)




Cours particulier pour la chère Sharon :

(a) les phrases au futur :
- The Widget will print the report
- The Widget will save the file
- The email will be sent if a network is found (futur composé)

 (b) les phrases au présent (et à la voix active) :
- These steps may prevent the brake pedal from functionning
- Your report prints
- During these steps, the brake pedal does not work
(c) Phrases au passé composé (et au passif)
- Your email is automatically sent the next time a network is found
- The file is saved
                                                                                                                      

Conclusion, le minimalisme ne consiste pas à minimaliser l'application des règles de
grammaire et de conjugaison, mais à bien veiller que tout ce qui est écrit est grammaticalement correct.


Il faut que l'utilisateur comprenne facilement ce qui est indiqué, mais aussi que le traducteur n'ait pas à DEVINER ce que l'on a voulu dire...

08/09/2013

Documentation minimaliste ?... pas dans le nucléaire !

Sûreté de fonctionnement : gros pavé ?

Pour garantir la sûreté d'utilisation et de fonctionnement dans le domaine du nucléaire, il
faut une documentation volumineuse, coûteuse et  conçue par des ingénieurs  dans un format établi et immuable.

C'est à ce prix que l'on contribue à la qualité d'utilisation des outils, machines et mécaniques... non ?


La vanne qui ne fait pas rire... 

C'est le titre de l'article publié le 4 septembre 2013 par le Canard Enchaîné qui relate les (graves) problèmes de montage d'une  
"vanne destinée à injecter des additifs chimiques dans un circuit de sécurité" Elle a été montée à l'envers !
"Ce défaut de montage a été tardivement repéré, car, parmi les "facteurs aggravants", les inspecteurs disposaient d'une "documentation de référence peu lisible".


AREVA et le mode d'emploi

Et, plus grave, dans la documentation :

  "la position du moteur était erronée" ! Le mode d'emploi était écrit en chinois ?"

(Le Canard Enchaîné du 4.09.2013)

Minimalisme et nucléaire

Gageons que cette documentation n'appliquait pas les principes du _minimalisme_
Pourquoi ? 


Si la documentation de montage induisait l'utilisateur en erreur, c'est que le rédacteur n'avait pas suivi le 2e principe du minimalisme :

"Se focaliser sur les véritables tâches de l'utilisateur",

 c'est-à-dire :
  • appréhender ces tâches dans l'environnement de l'utilisateur (sur son lieu de travail)
  • faire une véritable analyse des tâches et des utilisateurs.
(Voir l'article du Dr. Hans van der Meij : Anchor the tool in the task domain .


 Analyse des tâches de l'utilisateur

Dans le cas présent, il fallait demander à l'ingénieur/technicien spécialiste des vannes de simuler, dans l'environnement de travail, une installation.

L'idéal est de filmer les manipulations et d'enregistrer les explications de l'expert-métier. Bien entendu, le rédacteur, pendant l'interview, ne se contente pas de commenter "ah oui, ah bon, ah c'est d'accord..."

 
Mais il lui faut poser les questions les plus saugrenues possibles :

"Pourquoi prenez-vous la vanne par ce côté ? Combien de personnes pour installer la vanne ? Pourquoi vous avez ôté cette vis ? Comment avez-vous pu identifier la bonne vanne ? Où sont les références ? Pouvez-vous me montrer l'alimentation ? Comment vérifier que le montage est correct ? etc."


 Illisible ou inintelligible, la documentation ?

Quant à la documentation de référence "peu lisible", on hésite : était-elle peu lisible parce
que rédigée en MAJUSCULES sur FOND NOIR  ou GRIS ? ou alors faut-il comprendre "peu intelligible", c'est-à-dire difficile à comprendre ?

Elle pêchait peut-être par omission (des esprits chagrins diraient que le rédacteur n'était pas très au fait de l'installation de vannes, alors il s'est contenté de documenter un minimum pour ne pas se tromper -ou se fatiguer à faire des recherches- MAIS ce sont là des propos de MAUVAIS ESPRITS...).

 

Supputations : comment en est-on arrivé à cette grave erreur ?

On peut fort bien s'imaginer que le rédacteur n'a pas vu ni manipulé la vanne et qu'il se soit contenté d'une illustration (fiche produit). A partir de là, il a probablement _imaginé_ comment l'installer sur les circuits existants. Ce qui expliquerait une autre grosse bévue relevée dans le rapport d'inspection :

"Pas de connaissance de l'existence de différences de diamètre entre les orifices"...

 

Conclusion : le minimalisme dans la réalité

 La documentation basée sur les principes du minimalisme, ce n'est pas le rédacteur qui s'investit de façon _minimaliste_ dans son job, mais au contraire, celui qui fait des recherches approfondies et précises sur l'environnement de travail de l'utilisateur pour lui fournir une documentation correspondant à ses besoins !



___________________________________________
N.B Évalué à son lancement en 2005, à 3,3 milliards d'euros, l'EPR devrait finalement revenir à 8,5 milliards d'euros. Des malfaçons ont émaillé sa construction. Un exemple : les consoles du bâtiment réacteur - 45 appendices destinés à soutenir un pont roulant - présentaient des défauts de soudure (quotidien Ouest-France du 6 septembre 2013)

15/07/2013

L' atelier "minimalisme et document procédural" en France : la FAQ


Pour 2015, si vous souhaitez co-organiser un atelier "Documentation minimaliste" en vos locaux, contactez les organisateurs. 

La FAQ du minimalisme


1. Le minimalisme, ça sert à quoi ?
Certainement pas à réduire la taille des mots ni à tronquer les phrases.
L'objectif est de donner à l'utilisateur (du produit et donc de la documentation) uniquement l'information dont il a besoin.  C'est le bla-bla, les considérations inutiles que l'on élimine, pas l'information utile.

Le minimalisme sert aussi à réduire le coût de l'infobésité



2. Le minimalisme ? Pas besoin de ça chez nous !

Une documentation "minimaliste" est utile et efficace, parce que _lue par les utilisateurs_.

...alors que la mauvaise documentation peut coûter 13,8 milliards de dollars par an !

Si vos clients vous retournent les produits, les utilisent très peu et très mal, ils ne vont pas, lors d'un autre achat, revenir vers votre catalogue !



Vos clients ont une bonne opinion de vos produits et de votre documentation. Ils n'en parlent pas comme ça, n'est-ce pas ? 






3. Rédiger pour le client du 21e siècle
Est-ce vraiment nécessaire, en entreprise, de rédiger la documentation  comme à l'époque de la machine à écrire mécanique ?

A votre avis, n'a-t-on pas progressé depuis les années 60 ? 


Avez-vous interrogé vos clients sur l'utilité des manuels et guides que vous fournissez ? 

Avez-vous une idée du temps passé par l'équipe du SAV à répondre aux appels des clients :

("Patron ?!! La hot-line est surchargée !!! C'est toujours les mêmes questions qui reviennent !...")
    Voici ce qu'en pense l'initiateur du site I Fix It :
"Guides and manuals have to be designed to be effective in the world we live today - not the world that we lived in 40 years ago.

It's the only way that documentation will ever get the respect and the attention it deserves".

4. Que produisent vos rédacteurs et à quel prix ?

Votre équipe de rédaction est en place depuis plusieurs années. Les rédacteurs connaissent bien vos produits.


Avez-vous pris le temps de vérifier l'utilisabilité de la documentation produite ?

Par exemple, le manuel utilisateur ne décrit pas en 10 lignes comment imprimer une page A4... 

Quelque chose comme :

IMPRIMER AVEC L'IMPRIMANTE ABC
L'imprimante ABC vous permet d'imprimer des feuilles au format A4.
Le format A4 est le format de lettre commerciale.


Pour imprimer avec l'imprimante ABC
- mettez l'imprimante sous tension
- sélectionnez la fonction "Imprimer" qui se trouve sur le menu
- tapez le nombre de feuilles à imprimer
- appuyez sur OK

Si l'imprimante ne fonctionne pas, éteignez et rallumez.
Sinon, appelez la hotline


...et ensuite vous faites traduire ce chef d'oeuvre de lapalissades en 28 langues ;-(((



5. Le minimalisme ne m'intéresse pas ; moi, je fais du DITA
Le minimalisme est indispensable à la rédaction sous DITA ("DITA authoring")
C'est exactement ce que pense Adobe.



6. Le minimalisme, c'est tout nouveau !
Jetez un oeil sur ce récapitulatif : Le minimalisme ça vient d'où ? 


Ce n'est pas vraiment récent, puisque le premier ouvrage "The Nurnberg Funnel" date de 1990 ! Depuis, les principes n'ont fait que se préciser et s'améliorer.

7. Une formation éligible au DIF ? Y ai-je droit ? Comment faire ?
Le Droit Individuel à la Formation, c'est pour vous. La preuve...  


Ce DIF en 10 points va également compléter votre information.


8. Un atelier ?... ça fonctionne comment ?

Pas question de cours magistral, pas d'apprentissage par coeur, pas d'entonnoir de Nurnberg...mais de l'action, voire de l'interaction. 


Pendant deux jours, le travail s'organise en petits groupes. A partir d'exemples concrets apportés par les participants, on met en application les principes du minimalisme. Résultat : chacun repart avec SA PROPRE DOCUMENTATION "minimalisée"!


9. Le minimalisme, c'est avec quel logiciel ?  Combien coûte-t-il ?

Le minimalisme n'est lié à aucun logiciel ; c'est le contenu et non pas l'outil documentaire qui importe. Quel que soit votre outil usuel (y compris la plume d'oie...) vous pouvez adopter et pratiquer la rédaction minimaliste. 

Lors de l'atelier, votre seul outil, ce sont vos cellules grises !



10. Le minimalisme est réservé à la documentation logicielle
 Idée tristement fausse. 

Dans son webinaire du 12 juin 2013, Dr. JoAnn Hackos a confirmé appliquer les règles du minimalisme à la documentation de matériel médical. 

Les ateliers précédents ont accueilli des participants du secteur forage et exploration pétrolière, gestion d'immeubles, tracteurs et machines agricoles, téléphonie, gestion de réseau internet, matériel médical, etc.

L'atelier se tient exclusivement en français, par un formateur francophone.



11. Faut-il faire l'acquisition de manuels d'apprentissage ?
 Ce n'est pas indispensable. Une bibliographie mise à jour vous sera remise lors de l'atelier.
 

Toutefois, vous repartirez avec votre support de cours -en français- et un recueil d'exercices et exemples en français.


12. Le minimalisme a vraiment été mis en place dites-vous ? Chez qui ?


Tous les grands noms s'y sont mis, sans hésitation !



 Avec la documentation minimaliste, les coûts de conception ne portent que sur le contenu UTILE et EFFICACE pour une utilisation satisfaisante du produit.
 L'utilisateur n'ouvre jamais le manuel... sauf quand il a besoin d'une information précise. La trouve-t-il vraiment et rapidement dans votre documentation ?

 Savez-vous qu'un rédacteur non formé est plus coûteux qu'un véritable rédacteur professionnel ? 

L'amateur rédige pour le plaisir de rédiger (façon romancier) et produit des romans-fleuves inexploitables. Le professionnel rédige pour satisfaire aux attentes de l'utilisateur : il pense ergonomie, économie et utilisabilité !

En formant vos collaborateurs au minimalisme, non seulement vous les fidélisez, mais vous les préparez à la documentation sous DITA et à la rédaction en mode 'agile'
 A quoi peut servir un budget formation, sinon à former les collaborateurs pour les rendre plus compétitifs, à l'image de votre entreprise ?

 Se former en petits groupes, à partir d'exemples concrets, est-ce que ce n'est pas 
la solution optimale ?


Un manuel rédigé selon les règles du minimalisme a 90 % plus de chances d'être lu et utilisé qu'un manuel ("pavé") à l'ancienne !
 A votre avis, est-ce que vos concurrents ou vos sous-traitants ne sont pas en train de se former, eux, au minimalisme ?
 

01/07/2013

Minimalisme : les Dix Commandements

A mon humble avis, ceci est à mettre au-dessus de tout 
poste de travail d'un rédacteur technique :



1. Minimalist writing means including the least amount of content that is necessary for user success.

2. New users aren't interested in concepts.They want to jump in and try the product.

3. Minimalist writing means not offending the user's intelligence



________________________________________


4. Remove text about text.Must you tell the reader what the chapter contains, or can you get to the point?

5. Choose an action-oriented approach. Ensure that tasks follow an actual user workflow (a day in the life of...)

6. Include information that is more useful, well-suited to the task, and more action-oriented.

7. To slash verbiage, include fewer words, less description, and no useless information.



 ______________________________________

8. Give users a chance to be successful: get started quickly - jump into a task. 

9. Pay attention to what the user is perceiving,

 what is in their environment.


10. Don't focus on product specs and features; focus on what users need to do to be successful.



_____________________________________________________________
Ces règles sont extraites du webinar du 18 aout 2010, mené par JoAnn Hackos, sur le minimalisme et sponsorisé par Acrolinx [http://www.acrolinx.com/]