Ceci est un texte traduit automatiquement qui peut contenir des erreurs !
Une bonne documentation est la différence entre se souvenir de la manière dont les choses fonctionnent et se retrouver bloqué un dimanche à 23h parce que le serveur est hors service et que personne ne se rappelle comment il a été configuré. La documentation n’est peut-être pas la partie la plus passionnante de l’exploitation informatique, mais c’est l’une des plus importantes.
Pourquoi documenter ?
| Raison | Explication |
|---|---|
| Mémoire | Vous ne vous souviendrez pas de tout dans six mois, et vous n’avez pas besoin de le faire |
| Collaboration | D’autres doivent être en mesure de comprendre ce que vous avez fait sans vous le demander |
| Dépannage | Lorsque quelque chose ne va pas, il est inestimable de savoir ce qui est normal |
| Reconstitution | Si un serveur tombe en panne, vous devez savoir exactement comment il était configuré |
| Traçabilité | Qu’est-ce qui a été modifié, quand et par qui ? |
Écrivez la documentation pour votre « futur vous »
La meilleure règle d’or : écrivez comme si vous vous expliquiez les choses à vous-même dans six mois. Ainsi, vous êtes certain d’inclure suffisamment de détails sans pour autant trop compliquer les choses.
Types de documentation dans l’exploitation informatique
Carte réseau
Une carte réseau montre la structure physique et/ou logique du réseau. Cela peut aller d’un simple croquis à un diagramme détaillé comprenant les VLAN, les adresses IP et les règles de pare-feu.
Une bonne carte réseau devrait contenir :
- Tous les équipements réseau (commutateurs, routeurs, pare-feu, points d’accès)
- La structure VLAN avec les sous-réseaux
- Les adresses IP pour les équipements importants (serveurs, passerelle)
- Les connexions entre les équipements
Plan d’adressage IP
Un plan d’adressage IP est un aperçu de la façon dont les adresses IP sont distribuées dans le réseau. Il vous aide à rester organisé et à éviter les conflits (deux appareils avec la même adresse).
Exemple :
| VLAN | Nom | Sous-réseau | Passerelle | Plage DHCP | Notes |
|---|---|---|---|---|---|
| 10 | Administration | 10.0.10.0/24 | 10.0.10.1 | .100 - .200 | Accès limité |
| 20 | Employés | 10.0.20.0/24 | 10.0.20.1 | .100 - .250 | |
| 30 | Élèves | 10.0.30.0/24 | 10.0.30.1 | .100 - .250 | Uniquement internet |
| 50 | Serveurs | 10.0.50.0/24 | 10.0.50.1 | Aucune (statique) | Adresses IP fixes |
Adresses statiques :
| Adresse IP | Appareil | Rôle |
|---|---|---|
10.0.50.10 | web-01 | Nginx |
10.0.50.11 | db-01 | PostgreSQL |
10.0.50.12 | monitoring-01 | Grafana + Loki |
10.0.50.20 | proxmox | Hyperviseur |
Listes de contrôle
Les listes de contrôle garantissent que rien n’est oublié. Elles sont particulièrement utiles pour les tâches que vous effectuez moins souvent, comme la configuration d’un nouveau serveur ou la réalisation d’un examen de sécurité.
Exemple : Liste de contrôle pour un nouveau serveur Linux :
- Installer le système d’exploitation (Debian/Ubuntu)
- Mettre à jour tous les paquets (
sudo apt update && sudo apt upgrade) - Créer un utilisateur avec un accès sudo
- Désactiver la connexion root via SSH
- Configurer le pare-feu (
ufw) - Installer les logiciels nécessaires
- Configurer la sauvegarde
- Documenter le serveur dans le plan IP
- Tester le fonctionnement du service
Documentation des modifications
Chaque fois que vous effectuez une modification dans un environnement de production (serveur, réseau, service), vous devez la documenter. Un simple journal peut suffire :
## Journal des modifications
### 2026-04-14 - Mise à jour Nginx
- **Quoi :** Mis à jour Nginx de 1.24 à 1.26
- **Pourquoi :** Mise à jour de sécurité (CVE-2025-XXXX)
- **Qui :** Ola
- **Résultat :** OK, aucune interruption de service
### 2026-04-10 - Nouveau VLAN pour l'IoT
- **Quoi :** Création du VLAN 40 pour les appareils IoT
- **Pourquoi :** Isoler l'IoT du reste du réseau
- **Qui :** Kari
- **Résultat :** OK, toutes les imprimantes déplacées vers le VLAN 40
Utilisez Git !
Si vous rédigez la documentation dans des fichiers Markdown (recommandé), vous pouvez contrôler les versions avec Git. Vous aurez ainsi automatiquement un historique de toutes les modifications, et vous pourrez voir qui a modifié quoi et quand.
Documentation d’exploitation
La documentation d’exploitation décrit le fonctionnement d’un système dans son état actuel :
| Quoi | Exemple |
|---|---|
| Architecture système | “Nous exécutons Proxmox avec 3 VM : web, db, monitoring” |
| Informations d’accès | “SSH via le port 22, uniquement depuis VPN” |
| Routines de sauvegarde | “Sauvegarde quotidienne à 02:00 sur disque externe” |
| Informations de contact | “En cas de problème, contacter Ola (admin)” |
| Étapes de restauration | “Redémarrer avec : sudo systemctl restart nginx“ |
Outils de documentation
| Outil | À quoi il sert | Avantages |
|---|---|---|
| Markdown | Texte avec une mise en forme simple | Léger, portable, fonctionne avec Git |
| draw.io | Diagrammes et schémas de réseau | Gratuit, visuel, export vers image |
| Obsidian | Application de notes avec Markdown et liens | Idéal pour une base de connaissances personnelle |
| MkDocs | Publier Markdown sous forme de site web | Documentation professionnelle |
| Git/GitHub | Contrôle de version de la documentation | Historique, collaboration, sauvegarde |
Exercice 1 - Créer un schéma réseau simple
Utilisez draw.io (gratuit) pour dessiner le réseau à la maison ou à l’école :
- Commencez par la connexion internet et le routeur
- Ajoutez des commutateurs et des points d’accès
- Dessinez les serveurs, les PC et autres appareils
- Écrivez les adresses IP là où vous les connaissez
Il n’a pas besoin d’être parfait. L’objectif est de commencer à penser visuellement au réseau.
Exercice 2 - Créez votre propre liste de contrôle
Pensez à quelque chose que vous faites régulièrement avec l’informatique (par exemple, configurer une nouvelle VM, installer une machine de développement ou configurer VS Code). Écrivez une liste de contrôle pour le processus :
- Quelles sont toutes les étapes ?
- Qu’oubliez-vous le plus souvent ?
- Pouvez-vous simplifier certaines étapes ?
Enregistrez-la dans un document Markdown afin de pouvoir l’utiliser la prochaine fois.
Exercice 3 - Documentez l’un de vos services
Choisissez un service que vous avez mis en place (une VM, un conteneur Docker, un serveur web) et rédigez une courte documentation opérationnelle :
- Que fait le service ?
- Comment le démarrer/arrêter ?
- Quelle est l’adresse IP et le port ?
- Existe-t-il une sauvegarde ?
Écrivez cela en Markdown et placez-le dans un dépôt Git.
Résumé
- Documents pour votre futur vous : Écrivez comme si vous expliquiez à quelqu’un qui n’y connaît rien
- Schémas réseau et plans IP fournissent une vue d’ensemble de l’infrastructure
- Listes de contrôle garantissent que rien n’est oublié lors de tâches répétitives
- Journaux des modifications suivent ce qui a été fait, quand et par qui
- Documentation opérationnelle décrit le fonctionnement actuel des systèmes
- Utilisez Markdown + Git pour une documentation simple et avec contrôle de version