Ceci est un texte traduit automatiquement qui peut contenir des erreurs !
Une bonne documentation fait la différence entre se souvenir du fonctionnement des choses et être bloqué à 23 heures un dimanche parce que le serveur est en panne et que personne ne se souvient de sa configuration. 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 ? |
Skriv dokumentasjonen for “fremtidig deg”
La meilleure règle empirique : écrivez comme si vous expliquiez à vous-même dans six mois. Vous serez ainsi sûr d’inclure suffisamment de détails sans compliquer les choses.
Types de documentation dans l’exploitation informatique
Cartes réseau
Une carte réseau affiche la structure physique et/ou logique du réseau. Cela peut aller d’un simple croquis à un diagramme détaillé avec des VLAN, des adresses IP et des règles de pare-feu.
Une bonne carte réseau doit inclure :
- Tous les périphériques réseau (commutateurs, routeurs, pare-feu, points d’accès)
- La structure VLAN avec le sous-réseau
- Les adresses IP des périphériques importants (serveurs, passerelle)
- Les connexions entre les périphériques
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 :
## Endringslogg
### 2026-04-14 - Oppgradert Nginx
- **Hva:** Oppdatert Nginx fra 1.24 til 1.26
- **Hvorfor:** Mise à jour de sécurité (CVE-2025-XXXX)
- **Hvem:** Ola
- **Resultat:** OK, aucun temps d'arrêt
### 2026-04-10 - Nytt VLAN for IoT
- **Hva:** Opprettet VLAN 40 for IoT-enheter
- **Hvorfor:** Isoler l'IoT du reste du réseau
- **Hvem:** Kari
- **Resultat:** OK, toutes les imprimantes ont été 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