CNRS - DSI - Conduite de projet - Documentation utilisateur

Phase de développement - Technique
Développement spécifique
	Etude préalable Expression des besoins Cahier des charges fonctionnel Etude détaillée Dossier d'étude détaillée Modèle de données Règles d'ergonomie Etude technique et réalisation Dossier d'étude technique Tests de validation Conduite du changement Mise en oeuvre Bilan sites pilotes Documentation utilisateur Formation des utilisateurs
Développement avec progiciel

Documentation utilisateur
	1. Objet et domaine d’application 2. Documents de référence 3. Abréviations et terminologie 4. Principes d'élaboration 5. Contenu type 6. Annexe : conseils rédactionnels

1 - Objet et domaine d’application
Les manuels utilisateurs doivent être rédigés dans un souci de clarté et de facilité d'utilisation. Ils font partie des produits livrés à l'utilisateur au même titre que les applications logicielles. Ce document fait la synthèse des principales règles de composition pour la mise en page des documentations utilisateur des produits de la DSI.

Afin de faciliter le travail du rédacteur, nous avons construit un modèle de document (ou fond de page) disponible au format Word : " plan-type-documentation-utilisateur ".
Celui-ci est déjà paramétré suivant les règles exposées ici : feuilles de style, marges, options particulières, numérotation automatique des titres...

Pour aider les rédacteurs des documentations, ce document offre quelques conseils rédactionnels qu’il est utile de respecter et des conventions d’écriture qu’il est impératif de suivre.

Nota : le graphisme des couvertures de ce type de documentation est normalisé ; adressez-vous à la cellule Edition qui se chargera de les réaliser.

2 - Documents de référence

Plan type : " plan-type-documentation-utilisateur ".

3 - Abréviations et terminologie
Cf. glossaire " Conduite de projet système d'information "

4 - Principes d’élaboration

4.1 Mise en page générale

4.1.1 Enchaînement des informations

Niveau d’exigence	Règles d’enchaînement	Implémenté dans " plan-type-documentation-utilisateur "
	Tous les manuels doivent posséder une page de garde normalisée qui sera impérativement positionnée après la couverture et en page impaire ; le verso sera vierge de toute inscription.	page 1
	Tous les manuels doivent posséder une table des matières, faisant suite à la page de garde du document et commençant en page impaire.	page 3
	Dans le cas d’une documentation très volumineuse : chaque partie de niveau 1 composant le manuel devra comporter une page de garde annonçant la partie ; son verso sera vierge de toute inscription ; le style du titre de la partie est défini dans " plan-type-documentation-utilisateur " par le style Page garde.	oui
	Chaque première page des parties de niveau 1 devra obligatoirement commencer en page de droite (page impaire). Utiliser un saut de section avec première pas impaire.	non
	Tous les manuels devront comporter un chapitre 1 intitulé " A propos de ce manuel... " exposant l’objectif du document et les conventions d’écriture utilisées dans le document.	oui
	Les documents devront être présentés en recto/verso (fonction Word " Pages en vis à vis "). Certaines documentations peu volumineuses peuvent être présentées en recto seul pour faciliter la mise en œuvre (reprographie).	oui

Niveau d’exigence : = obligatoire ; = conseillé

La table des matières
Pour générer la table des matières, se positionner sur la page Table des matières de " plan-type-documentation-utilisateur "
Dérouler le menu Insertion/Table et index. Dans "Mise en forme" choisir Depuis le modèle.
Vérifier que dans Option/Construire la table des matières, la case <Style> est bien cochée et qu'il affiche bien trois niveaux de titres. La présentation de cette table des matières est définie selon les feuilles de styles TM1, TM2, TM3 qui s'appliquent aux trois premiers niveaux de titre du document.

4.1.2 Paramètres généraux de mise en forme du document

Niveau d’exigence

Règles de paramétrage

Implémenté dans " plan-type-documentation-utilisateur "

Les marges de page :
Haut : 2,5 cm
Bas : 2,5 cm
Intérieur : 3 cm
Extérieur : 2 cm

oui

En-tête de page :

extérieur de page = #chapitre courant#
intérieur = aucune mention

Pied de page :

intérieur = #nom de l’application# – #titre du document#
centre = #date du document# ou #version du logiciel#
extérieur = #numéro de page#

Typographie = Helvetica, italique, 10 pt (seul le numéro de page n’est pas italisé).

oui

Créer une commande

Page
paire

_______________________________________________________

Page
impaire

__________________________________________________________

10 Mars 1998 XLAB – Manuel d’utilisation

XLAB – Manuel d’utilisation Mars 1998 11

Abréviation des mois dans la date
Janv. Fév. Mars Avr. Mai Juin Juil. Août Sept. Oct. Nov. Déc.
Ex. : Juil. 1995

Inscription des versions
Ex. : V3.1


	Pagination La page de garde des documents n’est pas numérotée mais elle est comptabilisée ainsi que toutes les autres pages de garde dans le document.	oui
	Les versos laissés vierges ne doivent comporter aucune inscription (ni en-tête, ni pied de page) ; ils sont comptabilisés dans la numérotation des pages. Les sauts de section avec première page impaire gèrent automatiquement ces créations de pages vierges.	non

Niveau d’exigence : = obligatoire ; = conseillé

4.2 Typographie

Utiliser le style Normal pour votre texte courant.
Utiliser le style Normal-Action pour les enchaînements d’actions que doit réaliser l’utilisateur.
Les niveaux de titre sont limités à 3 : Titre 1 pour les chapitres + deux sous-niveaux de découpage ; au-delà, le Titre 4 (puce) doit être exceptionnel, il est préférable dans ce cas de réviser son découpage rédactionnel.

Pour les documents A5 composés sur un format A4 (réduction imprimeur) : augmenter d’un point toutes les valeurs de corps des styles suivants (Normal = 12 pt, Titre 1 = 18 pt, etc.).

oui

non

Le texte courant

Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal Normal

Times 10, retrait gauche 1,5 cm, justifié.

La description d’une ou plusieurs actions

– Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action.
– Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action Normal-Action

Normal + numérotation Puce

Les niveaux de titres

Aucun titre n'est justifié et leur numérotation est automatique.

Titre 1

Helvetica 16, gras, centré, interligne exactement 18 pt, espacement avant 10 pt après 15 pt, encadrement simple ombré. Il est sans numérotation visible.

Premier paragraphe sous le titre 1 : times 10, retrait à gauche de 1,5 cm, justifié, espace avant 15 pt. Ce style est à utiliser dans le cas où le titre 1 est immédiatement suivi par du texte (et non un titre), il permet de gérer un espace suffisant entre les deux.

1. Titre 2

Helvetica 14, gras, interligne exactement 18 pt, espacement avant 15 pt, après 10 pt. Numérotation du titre automatique.

1.1. Titre 3

Helvetica 12, retrait à gauche 0,5 cm, interligne exactement 18 pt, espacement avant 10 pt, après 5 pt. Numérotation du titre automatique.

• Titre-Puce

Normal 12 pt + gras, retrait à gauche 0,5 cm, numérotation Puce.

4.3 Conventions d'écriture

4.3.1 Attributs graphiques

Pour mettre en valeur des informations :

Utiliser exclusivement trois attributs graphiques caractérisant trois types d’informations.
Il est important de bien mesurer le poids de l’information mise en valeur par ces attributs afin de bien choisir le type d’attribut et de ne pas en abuser.

	Ce pictogramme identifie des remarques utiles mais sans incidence sur le cours des instructions exposées.
	Ce pictogramme identifie des informations à lire et/ou à exécuter impérativement qui peuvent influencer le cours des instructions suivantes.
	Ce pictogramme identifie un renvoi vers un chapitre, une partie ou une page où est décrite la suite des instructions.

Nota : la gestion des renvois dans le document peut être réalisée avec la fonction Insérer/Renvoi de Word.

4.3.2 Attributs typographiques

Attributs typographiques dans le cours de la rédaction :

Type de texte	Attribut	Exemple
Texte tapé par l'utilisateur	en courier	Taper : ? + <Tab> Taper : o pour Oui
Noms de bouton, bouton radio, case ou icone qui doivent être cliqués	entre <signe sup. et signe inf.>	Cliquer sur <OK> Cliquer sur le bouton <Ajouter>
Noms de logiciel ou d’application cités dans le texte	en texte normal	Xlab, Labintel/2 Unité, GCF...
Nom de fichier, nom de dossier	en MAJUSCULES	Transfert du fichier D_XLABO.9 Fichier de type A_XLABO.NNN Ouvrir le fichier CONFIG.SYS
Tous les noms de menu ou chemin par menu déroulant	en gras italique séparé par des / sans espace ni avant ni après	Dans le menu Fichier/Imprimer...
Les noms de champs, de rubriques, de fenêtre ou d’options	"entre guillemets"	Sélectionnez l’option "Titre"... Dans la rubrique "Commande" choisissez l’option "Demande d’achat"…
Raccourcis clavier	La première lettre en majuscule et le reste en minuscule séparé par + Voir normalisation des touches clavier ci-après.	Ctrl + M Alt + P Tab + ? Pomme + P
Formats de date	entre guillemets " "	"jj/mm/aa"

4.3.3 Vocabulaire

On emploiera le verbe :

cliquer en parlant d'un bouton ou d'un icone,
activer en parlant d'un bouton radio,
cocher en parlant d'une case,
sélectionner en parlant d'une option de menu,
taper en parlant d'une touche,
saisisser en parlant d’une frappe au clavier.

Il faut écrire...	... et non	Règle
Monoposte	mono-postes	s’accorde avec son sujet lorsqu’il est adjectif. ex. : une utilisation monoposte ; des utilisations monopostes.
Multiposte	multi-postes	idem ex. : une utilisation multiposte ; des utilisations multipostes.
c’est-à-dire	c’est à dire
PowerMac	Power Mac ou Power Macintosh ou Power PC
un icone	une icône
1^re, 2^e, 3^e...	1^ère, 2^ème, 3^ème...	abréviation des nombres ordinaux
ex. ou Ex.	ex ou Ex	abréviation de exemple
a: ou c:	a ou c	nom de périphériques
– (tiret moyen = Alt + 0150)	- (trait d’union)	utilisé comme début de phrase dans une suite d’actions descriptive
des Mac, des PC	des Macs, des PCs	les sigles ne sont jamais accordés
Mac	MAC	abréviation de Macintosh
AppliX V0.0 Ex. : Xlab V3.1	AppliX version 0.0 Ex. : Xlab version 3.1	mention des numéros de version dans le texte
mél.	mail ou e-mail	adresse électronique
Cliquez	cliquez une fois ou simple-cliquez	manipulation de la souris
Double-cliquez	cliquez deux fois	manipulation de la souris
la fenêtre X apparaît	la fenêtre X s’affiche	affichage d’une fenêtre à l’écran
le lecteur de disquette a: ou le disque dur c: ou sur le disque c:	sur a ou sur c	nom de périphériques

4.4 Normalisation des noms des touches clavier

5 - Contenu type

Voir les indications fournies dans le document " plan-type-documentation-utilisateur ".

6 - Annexe : Conseils redactionnels

Rédiger des phrases efficaces.

6.1 Conseils sur la forme rédactionnelle à adopter

1. Les formes grammaticales utilisées doivent être constantes dans l’ensemble d’un document.
Constance dans l’exposé des instructions, constance dans les intitulés de chapitres et de paragraphes.

2. Utiliser la voix active (rendre le lecteur acteur de la mise en œuvre des instructions exposées dans le texte).
Ex. : Mettre à jour les informations (au lieu de : Les informations doivent être mise à jour)

3. Centrer les titres sur des actions.

Ex. : Sauvegarder les données (au lieu de : La sauvegarde des données)

4. Utiliser l’impératif dans le déroulement des instructions.

Ce conseil peut être appliqué selon le type de manuel rédigé ; il est fortement conseillé pour les manuels d’installation (instruction pas à pas), il peut être remplacé par l’infinitif selon le type de relation (personnelle ou impersonnelle) que l’on désire établir avec le lecteur. Dans tous les cas, le choix doit être homogène à l’intérieur d’un même manuel.

Ex. : Impératif : Cliquez sur le bouton <OK>

Infinitif : Cliquer sur le bouton <OK>

5. Utiliser le présent (inscrire le lecteur dans l’action immédiate)

Ex. : Les opérations décrites permettent de... (au lieu de : Les opérations décrites permettront de...)

6. Etre parfaitement homogène dans l’écriture de mots, groupes de mots, expressions... quel que soit l’endroit où il apparaît dans le document (y compris les en-têtes et pieds de page).

7. Etre très explicite quitte à être redondant, en évitant les raccourcis d’écriture.

Ex. : La fenêtre présente les fonctionnalités du programme d’installation LB30INST. (au lieu de : La fenêtre présente les fonctionnalités de LB30INST). Ce problème se rencontre uniquement lors de l’installation. (au lieu de : Ce problème se rencontre uniquement dans LB30INST.)

8. Formuler les phrases de manière positive.

6.2 Conseils sur le fond

1. Présenter les conditions avant les actions.

Ex. : Si votre unité est créée en 1998, vous devez initialiser de nouvelles données.

2. Présenter les actions avant leurs effets.

Ex. : Cliquez sur <OUI> pour valider, cliquez sur <NON> pour revenir...

3. Les phrases d’introduction de paragraphes ne sont utiles que lorsqu’elles apportent une valeur ajoutée au titre ; elles ne doivent pas se contenter de les paraphraser.

4. Présenter en premier lieu les cas liés au contexte exposé, puis ceux liés aux situations futures (les remarques seront ainsi positivées).

Ex. : Ce problème se rencontre uniquement lors de l’installation, il ne se pose pas dans la manipulation de l’application. (au lieu de : Ce problème ne sera pas rencontré dans l’application mais uniquement dans l’installation.)

5. Annoncer explicitement les consignes ou tâches à effectuer.

Ex. : Si vous avez... vous devez renommer certains fichiers comme suit : <suivent les opérations de renommage>. (au lieu de : Si vous avez... effectuer les opérations suivantes : <suivent des opérations de renommage>.)

6.3 Copies d’écran

1. Contenu de l’écran :

il doit être identique à celui qu’aura sous les yeux l’utilisateur (mêmes menus, mêmes boutons...) ;
les données qu’il contient doivent être vraisemblables et correctes (éviter les toto, 000...) ;
dans les applications contenant des données nominatives, il est préférable d’illustrer les exemples avec de faux noms tels que Durand,ou Dupond.

2. Quand les utiliser :

lorsqu’elles apportent une valeur ajoutée à l’instruction ou lorsqu’elle permettent de simplifier l’instruction textuelle ;
elles sont inutiles lorsque l’élément que l’on veut signaler est suffisamment représentatif pour être extrait de la fenêtre elle-même et indépendant du reste de la fenêtre et lorsque la fenêtre ne comporte que des icones ou bouton-icone (pas de zone de saisie, ni de sélection à effectuer).

Ex. : l’icone "Poste de travail" du bureau, l’icone "Disquette A:" de la fenêtre "Poste de travail", le bouton-icone <Installation xx> d’une fenêtre " Installation ".

elles sont inutiles lorsqu’il s’agit de messages d’information (avertissement ou erreur) explicites qui sont lus en même temps à l’écran.

3. Positionnement :

chaque copie d’écran sera positionnée à la suite de l’action qui la concerne.