Download - Cours du CNAM 2013 - Conseils pour la documentation technique

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


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)


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)


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


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.

• ….


Amélie Vernusset 7


• 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


Amélie Vernusset 8


• 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….)


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…


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



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



La mise en forme


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



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



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



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.



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



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