Rédaction technique
Écrire
pour être compris
Guide utilisateur, documentation technique, rapport de projet, README — principes, structures et exemples concrets.
01
Principes universels
Quel que soit le type de document, cinq principes fondamentaux s'appliquent toujours.
Un objectif, un documentDéfinir en une phrase ce que le lecteur doit pouvoir faire après lecture. Si la phrase est floue, le document le sera aussi.
Écrire pour le lecteur, pas pour soiLe rédacteur connaît le sujet. Le lecteur ne le connaît pas. Toujours se demander : "Qu'est-ce que mon lecteur sait déjà ?"
La concision est une vertuChaque phrase doit apporter une information. Supprimer les adverbes inutiles, les formules de politesse vides, les répétitions.
Structure prévisibleLe lecteur ne lit pas linéairement. Utiliser des titres, listes, tableaux pour permettre le parcours rapide (scanning).
La documentation se périmeUne doc non maintenue est pire qu'une absence de doc — elle induit en erreur. Prévoir un responsable et une date de révision.
✗ Flou & verbeux
Il convient de noter que, dans le cadre de l'utilisation normale du logiciel, il peut s'avérer nécessaire, dans certains cas, de procéder à une vérification des paramètres de configuration avant de lancer l'application.
✓ Direct & concis
Avant de lancer l'application, vérifier les paramètres de configuration (fichier
config.ini).✗ Passif & ambigu
Le bouton doit être cliqué, puis le formulaire sera rempli et les informations seront sauvegardées.
✓ Actif & précis
1. Cliquez sur Enregistrer.
2. Remplissez les champs obligatoires.
3. Cliquez sur Valider.
2. Remplissez les champs obligatoires.
3. Cliquez sur Valider.
💡
Verbes d'action à l'impératif pour les procédures : "Cliquez", "Saisissez", "Sélectionnez". Pas "Il faut cliquer", pas "L'utilisateur devrait saisir".
02
Analyser son public cible
Le même sujet s'explique différemment selon le lecteur. Définir explicitement le public avant de commencer à rédiger.
| Public | Connaissances supposées | Besoins | Style adapté |
|---|---|---|---|
| Utilisateur final secrétaire, client, employé |
Aucune connaissance technique | Accomplir une tâche précise, sans comprendre le pourquoi | Langage courant, captures d'écran, pas de jargon |
| Technicien / Développeur collègue, intégrateur |
Bonne base technique du domaine | Comprendre le fonctionnement, pouvoir adapter | Précis, schémas d'architecture, exemples de code |
| Chef de projet / Manager commanditaire, jury de stage |
Contexte métier, peu de technique | Vue d'ensemble, résultats, risques | Résumé exécutif, tableaux de synthèse, visuels |
| Public mixte rapport annuel, mémoire |
Hétérogène | Plusieurs niveaux de lecture | Résumé + corps + annexes techniques |
ℹ️
Si le document s'adresse à plusieurs publics, utiliser une structure en oignon : résumé (tous les lecteurs) → corps principal (lecteur cible) → annexes (experts). Chaque lecteur s'arrête au niveau qui lui suffit.
03
Style & ton selon le document
Guide utilisateur
Tutoriel, bienveillant, rassurant. Guidage étape par étape. Le lecteur peut être stressé ou peu confiant.
"Pour ajouter un utilisateur, suivez ces étapes :"
Guide technique
Factuel, neutre, précis. Le "pourquoi" est aussi important que le "comment". Le lecteur veut comprendre.
"Le service expose un endpoint REST en POST sur /api/v1/users"
Rapport de stage/projet
Formel, structuré, objectif. Mélange narration (contexte) et analyse (résultats, recommandations).
"Cette phase a permis d'identifier trois axes d'amélioration..."
README / doc de code
Direct, minimaliste, orienté développeur. Aller droit au but. Le lecteur veut être opérationnel en 2 minutes.
"## Installation\n```bash\nnpm install && npm start\n```"
04
Guide utilisateur (end-user)
Destiné aux utilisateurs finaux sans expertise technique. L'objectif est de permettre l'accomplissement d'une tâche, pas d'expliquer le fonctionnement interne.
Structure recommandée
À adapter selon la complexité du logiciel/système
1. Page de titre
Nom du logiciel, version, date, auteur
2. Introduction
À qui s'adresse ce guide ?
Ce que le logiciel fait (1 paragraphe)
Prérequis (OS, navigateur...)
3. Installation / Démarrage
Étapes numérotées
Captures d'écran des écrans clés
4. Interface principale
Capture annotée de l'interface
Légende de chaque zone/bouton
5. Tâches principales
Une section par tâche courante
Titre = verbe d'action ("Créer un compte")
Étapes numérotées
Résultat attendu visible
6. Résolution de problèmes
Tableau Symptôme / Cause / Solution
7. Glossaire (optionnel)
Termes techniques expliqués simplement
Règles d'or du guide utilisateur
Une capture par étape cléL'image réduit l'ambiguïté à zéro. Annoter avec des flèches ou des cadres numérotés.
Numéroter toutes les étapesNe jamais utiliser des puces (•) pour des procédures séquentielles — l'ordre compte.
Indiquer le résultat attenduAprès chaque action, dire ce que l'utilisateur doit voir : "Le message 'Sauvegarde réussie' apparaît."
Zéro acronyme non définiSi un terme technique est indispensable, le définir au premier usage.
✗ Ambigu
Configurer les paramètres réseau puis relancer le service.
✓ Précis
1. Ouvrez Paramètres > Réseau.
2. Saisissez l'adresse IP fournie par votre administrateur.
3. Cliquez sur Redémarrer le service.
→ L'indicateur passe au vert.
2. Saisissez l'adresse IP fournie par votre administrateur.
3. Cliquez sur Redémarrer le service.
→ L'indicateur passe au vert.
05
Guide technique / développeur
Destiné à un public technique : développeur, intégrateur, administrateur système. Le pourquoi est aussi important que le comment.
Structure recommandée
1. Vue d'ensemble
Objectif du système/module
Diagramme d'architecture (schéma)
Stack technique (langages, frameworks)
2. Prérequis & environnement
Versions requises
Variables d'environnement
Dépendances externes
3. Installation & configuration
Commandes exactes (copiables)
Fichiers de config commentés
4. Architecture détaillée
Structure des dossiers
Flux de données
Décisions d'architecture (ADR)
5. API / Interfaces
Endpoints, paramètres, réponses
Exemples de requêtes/réponses
6. Tests
Lancer les tests
Couverture attendue
7. Déploiement
Environnements (dev/staging/prod)
8. Contribution
Convention de commits, branches
Règles d'or de la doc technique
Tout code doit être testableUn exemple de code non testé est un mensonge. S'assurer que chaque snippet fonctionne avant publication.
Justifier les décisions d'architectureExpliquer pourquoi X plutôt que Y. "Nous utilisons Redis plutôt qu'une DB relationnelle pour la session car..."
Versionner la documentationLa doc doit correspondre à une version précise du logiciel. Indiquer v1.2.3 en entête.
✗ Incomplet
L'API renvoie les données de l'utilisateur en JSON.
✓ Documenté
GET /api/v1/users/{id}
Réponse 200 :
Erreur 404 : utilisateur inexistant.
Réponse 200 :
{"id": 42, "nom": "Alice", "email": "..."}Erreur 404 : utilisateur inexistant.
06
Rapport de projet / stage
Document formel qui rend compte d'un travail accompli. Il doit être lisible par un public mixte : jury technique, tuteur académique, responsable d'entreprise.
Structure type d'un rapport de stage
Page de titre
Nom, prénom, établissement, entreprise
Titre du projet, date, version
Nom des tuteurs académique/entreprise
Remerciements
Court (½ page max), sincère, non générique
Résumé / Abstract
½ page max • Problème, approche, résultats
Version française + anglaise si requis
Table des matières
Numérotation sur 2-3 niveaux
Introduction
Contexte de l'entreprise/projet
Problématique
Objectifs et périmètre
Plan du document
Corps du rapport
État de l'art / analyse de l'existant
Conception / architecture
Réalisation / développement
Tests & validation
Bilan & perspectives
Objectifs atteints vs planifiés
Difficultés rencontrées
Améliorations possibles
Conclusion
Bibliographie / Webographie
Annexes
Code source clé, schémas détaillés
Manuel d'installation, tests complets
Erreurs classiques à éviter
✗ Introduction trop vague
Dans le cadre de mon stage, j'ai réalisé de nombreuses tâches intéressantes et enrichissantes qui m'ont permis d'acquérir des compétences variées.
✓ Introduction précise
Le stage s'est déroulé au sein de l'équipe backend de XYZ SA. L'objectif principal était de migrer l'API monolithique vers une architecture microservices, réduisant le temps de déploiement de 45 minutes à 8 minutes.
✗ Bilan sans analyse
Le stage s'est très bien passé. J'ai appris beaucoup de choses et je suis satisfait du résultat.
✓ Bilan analytique
Sur les 5 fonctionnalités prévues, 4 ont été livrées. La cinquième (authentification SSO) a été reportée faute de documentation de l'IdP. Les performances cibles (< 200ms) ont été atteintes sur 9/10 endpoints.
ℹ️
Résumé exécutif ≠ Introduction. Le résumé peut être lu seul. Il répond à : Quel était le problème ? Qu'a-t-on fait ? Avec quel résultat ? L'introduction contextualise et annonce le plan.
07
README & documentation de code
Le README est la première chose qu'un développeur lit. Il doit permettre d'être opérationnel en moins de 5 minutes.
Structure README — modèle
# NomDuProjet
 
Description en 2 phrases : ce que fait le projet et
à quel problème il répond.
## Prérequis
- Python >= 3.10
- PostgreSQL 15
## Installation
```bash
git clone https://github.com/user/projet
cd projet
pip install -r requirements.txt
cp .env.example .env # Remplir les variables
```
## Utilisation
```bash
python main.py --config config.yaml
```
## Tests
```bash
pytest tests/ -v
```
## Structure du projet
Voir ARCHITECTURE.md pour le détail
## Contribuer
Voir CONTRIBUTING.md
## Licence
MIT — erwin.desmet@heh.be
Documentation dans le code
Commenter le pourquoi, pas le quoiLe code dit ce qu'il fait. Le commentaire dit pourquoi il le fait ainsi.
Docstring sur toute fonction publiqueFormat Google, NumPy ou reST — choisir un format et s'y tenir dans tout le projet.
Référencer les sourcesSi un algorithme vient d'un article ou d'une réponse Stack Overflow, citer l'URL en commentaire.
✗ Commentaire inutile
# Incrémenter i de 1
i += 1✓ Commentaire utile
# Décalage de 1 : compenser l'index
# base-0 de l'API externe (doc §3.2)
i += 1
⚠️
Un README sans section "Installation" ou sans exemple d'utilisation est inutilisable. Ces deux sections sont non négociables.
08
Captures d'écran & visuels
Résolution suffisanteMinimum 1280px de large. Une capture floue est pire qu'aucune capture. Utiliser un outil de screenshot haute résolution.
Recadrer sur l'essentielNe pas capturer tout l'écran si seul un panneau est concerné. Zoomer sur la zone d'intérêt.
Annoter systématiquementNuméros dans des cercles, flèches rouges, cadres en surbrillance. Jamais une capture sans légende.
Mettre à jour à chaque versionUne capture d'une ancienne interface induit en erreur et décrédibilise toute la documentation.
Données fictives dans les capturesNe jamais capturer des données réelles (emails, noms, adresses). Utiliser des données de démonstration.
Quand utiliser quel visuel ?
| Visuel | Usage idéal |
|---|---|
| Capture annotée | Présenter une interface, localiser un bouton |
| GIF / vidéo courte | Démontrer une séquence d'actions (guide utilisateur) |
| Diagramme UML | Architecture, classes, flux (doc technique) |
| Flowchart | Processus décisionnel, algorithme |
| Tableau | Comparaison, liste de paramètres avec types |
| Graphique | Résultats de tests, mesures de performances |
💡
Numéroter toutes les figures (Figure 1, Figure 2…) et toujours y faire référence dans le texte. Ne jamais insérer une image sans explication dans le corps du texte.
09
Erreurs fréquentes
| Erreur | Symptôme | Correction |
|---|---|---|
| Jargon non défini | "Configurer le CIDR du VPC dans l'IAM" | Définir au 1er usage ou ajouter un glossaire |
| Étapes manquantes | "Installer Node.js puis lancer le projet" | Tester la procédure sur une machine vierge |
| Hypothèses implicites | "Ouvrir le terminal" (quel terminal ? comment ?) | Nommer exactement : "Ouvrir PowerShell en tant qu'administrateur" |
| Passif excessif | "Le formulaire doit être rempli" | "Remplissez le formulaire" — qui fait quoi ? |
| Mur de texte | Paragraphes de 10+ lignes sans titre | Découper en sous-sections, utiliser des listes |
| Version non mentionnée | Doc sans date ni version du logiciel | Toujours indiquer v1.2.3 et la date en entête |
| Doc non testée | Procédure qui ne fonctionne pas | Faire tester par quelqu'un qui ne connaît pas le sujet |
| Résumé = introduction | Résumé qui re-contextualise au lieu de synthétiser | Résumé = résultats + conclusion. Introduction = contexte + plan. |
10
Révision & relecture
Protocole de relecture en 3 passes
1
Passe structure — lire uniquement les titres et la table des matières. Le plan est-il logique ? Un lecteur peut-il naviguer sans lire le corps ?
2
Passe contenu — lire en détail. Chaque affirmation est-elle correcte ? Les exemples sont-ils valides ? Les procédures ont-elles été testées ?
3
Passe forme — orthographe, ponctuation, cohérence du style. Utiliser un correcteur (Antidote, LanguageTool) en complément.
ℹ️
Test utilisateur : faire lire le document par une personne du public cible. Observer ses points de blocage sans intervenir. C'est le test le plus révélateur.
Questions de relecture critiques
L'objectif du document est-il clair dès la première page ?
Le public cible est-il explicitement mentionné ?
Chaque étape de procédure est-elle testée sur une machine vierge ?
Tous les acronymes sont-ils définis au premier usage ?
Les captures d'écran correspondent-elles à la version actuelle ?
Le numéro de version et la date figurent-ils en entête ?
Y a-t-il un résultat attendu après chaque action ?
La bibliographie cite-t-elle toutes les sources ?
Le document a-t-il été relu par quelqu'un d'autre ?
11 — Référence
Checklists par type de document
✓ Guide utilisateur
| Page de titre avec version |
| Prérequis explicites |
| Étapes numérotées |
| Captures annotées |
| Résultat attendu après chaque étape |
| Section dépannage |
| Zéro jargon non défini |
| Testé par un non-technicien |
✓ Guide technique
| Diagramme d'architecture |
| Versions des dépendances |
| Snippets testés et reproductibles |
| Variables d'environnement listées |
| Justification des choix techniques |
| Section API documentée |
| Instructions de tests |
| Date et version en entête |
✓ Rapport de stage/projet
| Résumé ≠ introduction |
| Table des matières numérotée |
| Problématique clairement posée |
| Figures numérotées et légendées |
| Bibliographie normalisée (APA/ISO) |
| Bilan : objectifs atteints vs planifiés |
| Perspectives concrètes |
| Relecture externe |
✓ README / doc code
| Description en 2 phrases max |
| Prérequis avec versions |
| Installation copiable-collable |
| Exemple d'utilisation |
| Comment lancer les tests |
| Docstrings sur fonctions publiques |
| CHANGELOG ou historique |
| Licence mentionnée |