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 ...
Pourquoi faire une documentation technique ?
• Pour permettre aux utilisateurs de :
1. Comprendre comment fonctionne l’out...
4
Phase 1 – Réfléchir aux besoins de l’utilisateur
• Pour avoir une information pertinente :
– Décrivant ses tâches (et no...
Phase 2 – Rédiger la documentation
• En faisant attention à :
– Respecter les standards de présentation
– Être concis
– Re...
Phase 3 – Tests Utilisateur et post-production
• Intégrer dans les tests Utilisateurs (ne
connaissant pas l’outil) la docu...
Arriver à une information pertinente (1)
• Ex. Utiliser les outils de révision dans Word
• Le bouton Nouveau commentaire p...
Arriver à une information pertinente (2)
• Ex. Utiliser les outils de révision dans Word
Les outils de révision de Word pe...
Arriver à une information pertinente (3)
• Il faut se détacher de l’interface : la décrire est
tentant.
• La solution est ...
S’adapter à l’utilisateur
• Niveau : dépend de son niveau en informatique
– Ex. sélection multiple, double-clic, lancer un...
Documentation à jour
• Non mis à jour = information erronée, travail
inutilisable ou apportant de la confusion.
• Mise à j...
Standard de présentation
• Pas connu mais si pas appliqué, la
compréhension est difficile
• Mots appropriés (bouton radio,...
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 : term...
Ergonomie
• La doc technique utilise la mémoire
procédurale, aidons l’utilisateur :
– Succession d’étapes courtes (max. 7)...
Le contenu (1)
• Titre : verbe qui décrit ce que veut faire
l’utilisateur, en général verbe infinitif
• Introduction :
– e...
Le contenu (2)
• Corps :
Il vaut mieux séparer les longues explications
et les instructions
– Les instructions : avec des ...
Le contenu (3)
• A chaque étape, expliquer ce qui doit se
passer
Ex. Cliquer sur Nouveau. La fenêtre Nouveau
document s’ou...
Les captures d’écran
• A éviter sauf si ça apporte vraiment une
information supplémentaire et utile
Rappel : Les captures ...
Types de documentation technique
• A lire :
– Guide utilisateur, Guide de migration, Guide
administrateur, Guide de transi...
Prochain SlideShare
Chargement dans…5
×

Cours du CNAM 2013 - Conseils pour la documentation technique

1 021 vues

Publié le

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.

Publié dans : Développement personnel
0 commentaire
1 j’aime
Statistiques
Remarques
  • Soyez le premier à commenter

Aucun téléchargement
Vues
Nombre de vues
1 021
Sur SlideShare
0
Issues des intégrations
0
Intégrations
3
Actions
Partages
0
Téléchargements
11
Commentaires
0
J’aime
1
Intégrations 0
Aucune incorporation

Aucune remarque pour cette diapositive

Cours du CNAM 2013 - Conseils pour la documentation technique

  1. 1. Conception de documentation technique Quelques conseils et principes de base (Amélie Vernusset, élève INTD 2013)
  2. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 13. La mise en forme 26 avril 2013 Conception de documentation technique - Amélie Vernusset
  14. 14. La mise en forme 26 avril 2013 Conception de documentation technique - Amélie Vernusset
  15. 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. 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. 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. 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. 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. 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. 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

×