Conception de documentation technique
Quelques conseils et principes de base
(Amélie Vernusset, élève INTD 2013)
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
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
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
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
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
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
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
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
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
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
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
La mise en forme
26 avril 2013 Conception de documentation technique -
Amélie Vernusset
La mise en forme
26 avril 2013 Conception de documentation technique -
Amélie Vernusset
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:\documents\mes_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
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
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
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
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
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
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