Quelques conseils pour bien rédiger la documentation accompagnant des projets de gestion de l'information, par exemple, une base de données. Support du cours réalisé au CNAM pour les étudiants Bac+5 en 2013.

1. Conception de documentation
technique
Quelques conseils et principes de base
(Amélie Vernusset, élève INTD 2013)

2. Pour commencer positivement…
• Vous n’aurez pas envie de concevoir la
documentation technique
• Les utilisateurs n’auront pas envie de lire cette
documentation
Voyons ensemble comment faire pour que ce soit utile
à tout le monde !
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
2

3. Pourquoi faire une documentation technique ?
• Pour permettre aux utilisateurs de :
1. Comprendre comment fonctionne l’outil
2. Se souvenir des étapes pour réaliser les tâches
3. Savoir ce qu’il peut faire avec l’outil
• Pour vous, en étant à la place de l’utilisateur :
– Vérifier le bon fonctionnement
– Vérifier l’ergonomie
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
3

4. 4
Phase 1 – Réfléchir aux besoins de l’utilisateur
• Pour avoir une information pertinente :
– Décrivant ses tâches (et non des fonctionnalités)
– Adaptée à son niveau
– Apportant des informations non présentes dans
l’interface utilisateur
– À jour
Définir le périmètre de la documentation
Particularité de vos projets : se basent sur un logiciel
déjà documenté (On ne va pas refaire la doc Access)
26 avril 2013
Conception de documentation technique -
Amélie Vernusset

5. Phase 2 – Rédiger la documentation
• En faisant attention à :
– Respecter les standards de présentation
– Être concis
– Respecter les principes d’ergonomie
• Comment et quand :
– En testant l’outil en parallèle
– Avant la fin de la réalisation (pour modifier l’outil si
des problèmes sont détectés)
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
5

6. Phase 3 – Tests Utilisateur et post-production
• Intégrer dans les tests Utilisateurs (ne
connaissant pas l’outil) la documentation pour
vérifier qu’ils y trouvent les informations
nécessaires à la bonne utilisation de l’outil
• Après le lancement, les retours des
utilisateurs sur l’utilisation de l’outil
(questions, problèmes) permettent
d’améliorer la documentation et donc d’alléger
le travail de support
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
6

7. Arriver à une information pertinente (1)
• Ex. Utiliser les outils de révision dans Word
• Le bouton Nouveau commentaire permet d’insérer un
nouveau commentaire
• Le bouton Modifier un commentaire permet d’éditer
un commentaire existant.
• Le bouton Supprimer un commentaire permet de
supprimer le commentaire.
• ….
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
7

8. Arriver à une information pertinente (2)
• Ex. Utiliser les outils de révision dans Word
Les outils de révision de Word permet un travail
collaboratif sur un même document. Il est notamment
possible de :
– Insérer/Supprimer des commentaires.
– Suivre les modifications de différentes personnes
dans un document
– Comparer et fusionner deux versions d’un
document
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
8

9. Arriver à une information pertinente (3)
• Il faut se détacher de l’interface : la décrire est
tentant.
• La solution est de réfléchir :
– Aux tâches y compris celles qui impliquent
l’utilisation de plusieurs écrans/fenêtres
– Aux utilisations non « classiques » :
• Ex. Comment récupérer des données suite à une
mauvaise manipulation
• Ex. Comment travailler plus vite (touche de raccourcis,
changement en masse….)
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
9

10. S’adapter à l’utilisateur
• Niveau : dépend de son niveau en informatique
– Ex. sélection multiple, double-clic, lancer une ligne
de commande…)
• Contenu : dépend de ses utilisations mais aussi de
son expérience passée (ex. guide de transition)
• Environnement : Système exploitation, logiciel
installé/en ligne, vue fréquemment utilisée, langue
d’interface…
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
10

11. Documentation à jour
• Non mis à jour = information erronée, travail
inutilisable ou apportant de la confusion.
• Mise à jour rare sur les « petits » projets
(temps, motivation, oubli…)
• Solution : documentation facile à mettre à
jour par soi-même et d’autres personnes
– Limiter les captures d’écran
– Garder les sources (contenu, images/schémas)
– Choisir des logiciels accessibles et connus
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
11

12. Standard de présentation
• Pas connu mais si pas appliqué, la
compréhension est difficile
• Mots appropriés (bouton radio, liste déroulante…)
• Avec une mise en forme standard
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
12

13. La mise en forme
26 avril 2013
Conception de documentation technique -
Amélie Vernusset

14. La mise en forme
26 avril 2013
Conception de documentation technique -
Amélie Vernusset

15. La mise en forme standard d’une procédure
– Liste numérotées : les étapes
– Liste à puces : à faire au choix
– Gras : terme d’interface lié à une action
Ex. noms de boutons, champs ; pas de fenêtre
– Nom / chemin de fichier : c:documentsmes_doc
En italique
Chemin « copier-collable », pas de Documents > mes_doc
– Menu déroulant :
Fichier > Nouveau > Nouveau Document
– Texte à taper : police de type machine à écrire
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
15

16. Ergonomie
• La doc technique utilise la mémoire
procédurale, aidons l’utilisateur :
– Succession d’étapes courtes (max. 7) pour les
retenir
– Un concept ou objet = 1 mot, une mise en forme :
évite les doutes, aide à la mémorisation
– En un coup d’œil on doit pouvoir retrouver une
info oubliée (pas de grandes captures d’écran) à
chaque étape
– Besoin d’information qui confirme que c’est OK.
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
16

17. Le contenu (1)
• Titre : verbe qui décrit ce que veut faire
l’utilisateur, en général verbe infinitif
• Introduction :
– explication du contexte
– mise en garde (reformater clé USB perte des données)
– comment on arrive là pour pouvoir commencer
– Ce dont on a besoin
Ex. avoir créé un utilisateur pour créer un groupe
d’utilisateur
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
17

18. Le contenu (2)
• Corps :
Il vaut mieux séparer les longues explications
et les instructions
– Les instructions : avec des listes (2 niveaux max)
– Les explications : peuvent inclure des schémas,
graphiques, tableaux….
• Conclusion :
– où on en est quand on a fini
– Prochaines étapes
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
18

19. Le contenu (3)
• A chaque étape, expliquer ce qui doit se
passer
Ex. Cliquer sur Nouveau. La fenêtre Nouveau
document s’ouvre.
• Phrase très courte : 1 idée = 1 phrase.
• Phrase active, pas de phrase passive
• Phase affirmative (si possible)
A garder en mémoire : L’utilisateur ne lit pas de façon linéaire le
document, il cherche la procédure qui l’intéresse et ne sait pas ce
qu’il y a avant ou après. Chaque procédure se suffit à elle-même.
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
19

20. Les captures d’écran
• A éviter sauf si ça apporte vraiment une
information supplémentaire et utile
Rappel : Les captures sont difficiles à mettre à jour, il faut les
regarder une par une pour vérifier que l’interface n’a pas
changé
• Si utilisée, faire une capture de qualité :
– Possibilité d’identifier où l’on est (avec un coin, la barre du
haut…)
– Champs remplis correctement (suivant les instructions)
– Texte lisible sur la capture
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
20

21. Types de documentation technique
• A lire :
– Guide utilisateur, Guide de migration, Guide
administrateur, Guide de transition, Guide
d’installation, Aide en ligne, Manuel
• A suivre/à faire :
– Tutoriels, animation, support de formation…
• d’autres formats (flash, e-learning…)
• Il faut proposer une succession de procédures
• En indiquant les temps de réalisation, les niveaux…
26 avril 2013
Conception de documentation technique -
Amélie Vernusset
21