Qui doit l’utiliser ?

Posez toujours d’abord la question : Qui va utiliser le guide et quoi doivent-ils avoir accompli lorsqu’ils auront terminé ?

Un nouvel employé informatique qui maîtrise le terminal a besoin d’un autre guide qu’un enseignant qui ne l’a jamais ouvert. Le même système peut donc nécessiter plusieurs guides. Déterminez ce que le destinataire sait déjà, à quoi il a accès et quels termes lui sont inconnus.

Quel type de document est-ce ?

Un guide utilisateur est un guide d’action : il aide l’utilisateur à effectuer une tâche unique. Ce n’est pas un manuel pédagogique, un ouvrage de référence ou une explication des raisons pour lesquelles le système fonctionne comme il le fait.

Si l’utilisateur a besoin d’une explication en cours de route, gardez-la brève et placez-là là où l’en utiliseur en a besoin.

Les parties du guide

Comment rédiger une étape

Les règles sont basées sur les normes relatives aux instructions d’utilisation et à la documentation utilisateur (CEI/IEEE 82079-1 et ISO/IEC/IEEE 26514).

• Commencez chaque étape par un verbe au mode impératif : « Ouvrir », « Exécuter », « Vérifier ».
• Une seule action par étape et une seule instruction par phrase. Maintenez les phrases en dessous d’environ 20 mots.
• Décrivez ce que l’utilisateur doit voir lorsque l’étape est terminée.
• Placez les avertissements avant l’étape concernée, pas après.
• Utilisez le même terme pour désigner la même chose tout du long. Si on utilise « terminal » dans un endroit, il ne faut pas utiliser « console » ailleurs.
• Expliquez un jargon technique lors de sa première utilisation.

Étape faible :

Configurez le site web et vérifiez que tout fonctionne.
Meilleure étape :

3. Vérifier la configuration

Exécutez :

sudo nginx -t

Vous devriez voir :

nginx: configuration file /etc/nginx/nginx.conf test is successful

Si vous voyez autre chose, consultez « Dépannage ».

Commandes, résultat attendu et espaces réservés

• Placez les commandes dans un bloc de code et le résultat attendu dans un bloc distinct ci-dessous.
• Utilisez le formatage du code pour les noms de fichiers, chemins d’accès aux fichiers et commandes dans le texte courant, par exemple /etc/nginx/.
• N’écrivez jamais de mots de passe réels, de clés ou d’adresses internes. Utilisez des espaces réservés clairs : <server-ip>, <nom-utilisateur>, <domaine>.
• Gardez les lignes de code à moins d’environ 70 caractères afin qu’elles ne soient pas coupées sur papier.

Dépannage

Construisez le dépannage autour de ce que l’utilisateur voit :

Symptôme → causes possibles → investigation → solution → vérification

La méthode sous-jacente figure dans [[Méthode de dépannage Niveau 1 - Dépannage systématique|Méthode de dépannage]].

Captures d’écran

Utilisez une capture d’écran uniquement lorsqu’elle aide l’utilisateur à reconnaître un résultat correct. Recadrez l’image, mettez en évidence les éléments importants avec une flèche ou un numéro et supprimez toute information sensible. Rédigez un texte alternatif qui décrit ce que montre l’image.

• Windows : Touche Windows + Maj + S
• Mac : Cmd + Maj + 4

![Nginx Proxy Manager affiche le hôte du proxy avec le statut En ligne](images/proxy-online.png)

Imprimer en PDF

1. Ouvrez le guide dans l’aperçu de VS Code ou ouvrez le fichier sur GitHub.
2. Sélectionnez l’impression. Windows : Ctrl + P. Mac : Cmd + P.
3. Choisissez « Enregistrer au format PDF ».
4. Parcourez la version PDF. Vérifiez qu’aucune ligne de code, tableau ou image n’est coupé(e).

Obtenir des retours avant de livrer

Faites lire le guide par un collègue avant d’indiquer qu’il est terminé. La personne qui donne son retour répond brièvement et renvoie à l’emplacement pertinent dans le texte :

1. Exactitude : Y a-t-il des étapes ou des affirmations dont vous doutez ?
2. Destinataire et structure : Est-il clair pour qui est destiné ce guide et quelles sont les conditions préalables à remplir en premier lieu ?
3. Langage et action : Chaque étape contient-elle une seule action et un résultat attendu ? Les termes techniques sont-ils expliqués ?
4. Sécurité : Contient-il des éléments qui ne devraient pas être publiés ?

Indiquez deux points forts et deux améliorations concrètes. Soyez courtois et précis : « Je propose que vous expliez proxy à l’étape 2, car … » est plus utile que « flou ». Pour en savoir plus sur la manière de donner des retours : NDLA Comment formuler des commentaires ?.

Exercice 1 – Améliorer les étapes faibles

Réécrivez chaque étape de manière à ce qu’elle contienne un seul verbe au impératif, une seule action et un résultat attendu. Divisez les étapes qui contiennent plusieurs actions.

1. « Il faut maintenant démarrer le conteneur et vérifier qu’il fonctionne. »
2. « Modifiez la configuration, pensez à la tester ensuite puis rechargez-la. »
3. « Connectez-vous au serveur avec le mot de passe Sommer2026! et accédez au dossier du site web. »

Exercice 2 – Rédiger un court guide

Choisissez une tâche que vous pouvez effectuer sans aide, par exemple démarrer un conteneur ou publier une modification sur un site web.

1. Indiquez à qui le guide s’adresse et ce qu’ils seront capables de faire ensuite.
2. Écrivez trois à six étapes avec le résultat attendu.
3. Ajoutez au moins une ligne dans la résolution des problèmes.
4. Laissez un camarade suivre le guide sans que vous n’expliquiez rien. Corrigez l’étape où il a bloqué.

Pour aller plus loin

• NDLA : Rédiger des guides d’utilisation et des informations pour différents groupes d’utilisateurs
• NDLA : Développer du matériel pédagogique
• Språkrådet : Langage clair
• Diátaxis sur les quatre types de documentation (anglais)