Rédiger une documentation technique claire, utile et maintenable : procédures, schémas, wikis et guides d'exploitation.
Intermédiaire — SISR 1ère et 2ème année
⏱️ 20 min
📁 Méthodes
🎯 Objectifs de la fiche
- Pourquoi documenter ? — Valeur de la documentation, dette technique
- Types de documents techniques — Procédure, guide, schéma, FAQ, runbook
- Structure d'une procédure — En-tête, prérequis, étapes, vérification
- Schémas réseau et d'infrastructure — Conventions, outils, niveaux de détail
- Maintenir la documentation — Versionning, revues, wiki, responsabilités
Prérequis
Aucun prérequis technique spécifique — cette fiche s'applique à toutes les situations où un technicien ou ingénieur doit documenter une infrastructure, une procédure ou une configuration.
1. Pourquoi documenter ?
| Situation | Sans documentation | Avec documentation |
|---|
| Arrivée d'un nouveau technicien | Semaines de découverte, dépendance totale à l'ancien | Prise en main rapide, autonomie en quelques jours |
| Incident à 3h du matin | Stress, tâtonnements, délai de résolution élevé | Procédure de résolution claire, intervention rapide |
| Départ d'un collègue | Perte de connaissance critique, risque élevé | Continuité assurée, savoir-faire transmis |
| Audit de sécurité | Impossible de prouver la conformité des configurations | Preuves disponibles, audit facilité |
| Intervention prestataire | Doit tout expliquer, risque d'erreurs | Prestataire autonome avec la doc, intervention cadrée |
ℹ️ La dette documentaire (documentation absente ou obsolète) a un coût réel : temps perdu, erreurs, incidents prolongés. Comme la dette technique, elle s'accumule et devient de plus en plus coûteuse à rembourser.
2. Types de documents techniques
| Type | Objectif | Exemples |
|---|
| Procédure opérationnelle (SOP) | Décrire comment effectuer une tâche répétitive | Procédure de sauvegarde, création d'un utilisateur AD |
| Guide d'installation | Guider l'installation et la configuration d'un service | Guide install Apache2, guide config pfSense |
| Runbook | Réponses aux incidents courants step-by-step | Runbook 'serveur SSH inaccessible', runbook 'disque plein' |
| Schéma d'infrastructure | Représenter visuellement l'architecture | Plan réseau, schéma de virtualisation, topologie Cisco |
| Inventaire / CMDB | Lister et décrire les équipements et services | Tableau des serveurs, liste des VMs, inventaire switches |
| FAQ / Base de connaissances | Répondre aux questions fréquentes | FAQ utilisateurs, KB incidents courants |
3. Structure d'une procédure opérationnelle
┌─────────────────────────────────────────────────────┐
│ EN-TÊTE │
│ Titre : Création d'un utilisateur Debian │
│ Version : 1.2 │
│ Auteur : G. Hommet │
│ Date MAJ : Juin 2026 │
│ Validé par : Direction SI │
└─────────────────────────────────────────────────────┘
OBJET
Créer un compte utilisateur sur un serveur Debian 13
et lui attribuer les droits sudo si nécessaire.
PRÉREQUIS
- Accès root ou sudo sur le serveur cible
- Connaître le login et le rôle de l'utilisateur
ÉTAPES
1. Se connecter en SSH au serveur
2. Créer l'utilisateur : sudo adduser [login]
3. Si droits admin requis : sudo usermod -aG sudo [login]
4. Vérifier : groups [login]
VÉRIFICATION
- Tester la connexion avec le nouveau compte
- sudo whoami doit retourner root
CAS D'ERREUR
- "adduser: The user already exists" → l'utilisateur existe déjà
→ Vérifier avec : id [login]
4. Règles d'or de la rédaction technique
| Règle | Mauvais exemple | Bon exemple |
|---|
| Être précis | Redémarrer le serveur | sudo systemctl restart apache2 |
| Une tâche = une étape | Installer et configurer Apache | Étape 1 : Installer. Étape 2 : Configurer |
| Indiquer le résultat | Lancer la commande | Résultat attendu : Active: active (running) |
| Dater et versionner | Pas de date | Version 1.2 — Juin 2026 — mis à jour par G.H |
| Documenter les erreurs | (rien) | Si erreur X → cause probable Y → action Z |
| Éviter le jargon | Patcher le daemon avec les args corrects | Mettre à jour le service avec les bons paramètres |
💡 Testez votre documentation en la faisant suivre par quelqu'un qui ne connaît pas la procédure. Si cette personne bute sur une étape, la documentation est incomplète. La meilleure documentation est celle qu'un technicien junior peut suivre seul.
5. Schémas d'infrastructure
| Niveau | Contenu | Outils |
|---|
| Niveau 1 — Physique | Équipements physiques, câblage, baies, salles | Draw.io, Visio, LucidChart |
| Niveau 2 — Logique | VLANs, adressage IP, routage, zones de sécurité | Draw.io, NetBox |
| Niveau 3 — Service | Applications, flux de données, dépendances | Draw.io, Miro |
Conventions recommandées pour les schémas réseau :
Formes : Routeur = cylindre ou icône Cisco
Switch = rectangle avec lignes
Serveur = rectangle vertical
PC = rectangle avec écran
Cloud = forme nuage (Internet/WAN)
Firewall = rectangle avec flamme
Couleurs : Rouge = WAN / Internet (zone non fiable)
Orange = DMZ (zone démilitarisée)
Vert = LAN interne (zone de confiance)
Bleu = Gestion / administration
Étiquetage : Chaque lien = adresse IP + masque des deux côtés
Chaque équipement = hostname + IP de gestion
VLANs = numéro + nom
6. Maintenir la documentation
| Pratique | Fréquence | Responsable |
|---|
| Mise à jour après tout changement d'infra | À chaque changement | Technicien qui fait le changement |
| Revue complète de la documentation | Annuelle | Responsable SI |
| Test des procédures critiques | Semestrielle | Équipe technique |
| Archivage des anciennes versions | À chaque mise à jour | Technicien auteur |
⚠️ Une documentation obsolète est pire qu'une absence de documentation — elle induit en erreur. Mettez en place une règle simple : 'Si tu fais un changement, tu mets la doc à jour le même jour.'
7. Outils recommandés
| Outil | Usage | Type |
|---|
| Draw.io (app.diagrams.net) | Schémas réseau, flux, architecture | Gratuit, web/desktop |
| Confluence | Wiki d'entreprise, base de connaissances | Payant (gratuit jusqu'à 10 users) |
| Notion | Notes, procédures, base de connaissances | Freemium |
| GitLab/GitHub Wiki | Documentation versionnée avec le code | Gratuit |
| BookStack | Wiki auto-hébergé, open source | Gratuit, Docker |
| NetBox | IPAM, inventaire réseau et infra | Gratuit, open source |
- ☐ En-tête complet sur chaque document (titre, version, auteur, date)
- ☐ Prérequis clairement indiqués
- ☐ Étapes numérotées, une tâche par étape
- ☐ Résultat attendu indiqué pour les étapes critiques
- ☐ Cas d'erreur documentés
- ☐ Schémas réseau avec adressage IP et légende
- ☐ Processus de mise à jour défini
- ☐ Documentation stockée dans un outil accessible à toute l'équipe