Guidelines¶

Principes et conventions de cette documentation.

Ces guidelines s'appliquent à toute contribution, qu'elle soit faite par des humains ou des agents IA, et doivent être suivies rigoureusement pour assurer la cohérence et la qualité du contenu.

Principes Fondamentaux¶

1. État Réel vs Process¶

✅ Documenter l'état actuel du serveur

Configuration réelle en production
Chemins et commandes actuels
Valeurs et paramètres effectifs

❌ Ne pas documenter

Cheminement d'implémentation historique
États intermédiaires ou temporaires
Process de décision sauf si critique pour le futur
Statuts datés ("en cours le 28/01/2026")

Exemple :

✅ BON

## Backup PBS

- Datastore: `/mnt/datastore` (100GB)
- Rétention: keep-daily=7, keep-weekly=4, keep-monthly=3
- Scripts: `/usr/local/bin/backup-*.sh`

❌ MAUVAIS

## Backup PBS - Déploiement

Le 28 janvier nous avons déployé le backup...
Étape 1: créer le script...
Étape 2: tester...
État: En cours de finalisation

2. Pas de Redondance¶

Un fait = un endroit dans la documentation
Utiliser des liens entre pages plutôt que dupliquer
Pages index pour vue d'ensemble, détails dans sous-pages
Corriger ou augmenter le contenu existant plutôt que créer de nouvelles pages

Exemple :

✅ BON
Voir configuration [MergerFS](../storage/mergerfs.md) pour détails.

❌ MAUVAIS
MergerFS est configuré avec les options suivantes:

- cache.files=partial
- dropcacheonclose=true
  [...]
  (copier-coller depuis storage/mergerfs.md)

3. Référencer le Serveur, Pas Dupliquer¶

❌ Ne pas inclure le contenu des scripts/configs

Les scripts sont versionnés sur le serveur
Risque de désynchronisation

✅ Référencer par path et décrire

## Script Backup Host

**Path:** `/usr/local/bin/backup-proxmox-host.sh`

**Fonction:** Sauvegarde configs host Proxmox vers Google Drive

**Contenu sauvegardé:**

- `/etc/pve/` - Configs Proxmox
- `/etc/network/` - Réseau
- `/etc/fstab` - Montages

**Exécution:** Cron daily 05:00

4. Outils VS Code¶

Pour toute lecture ou modification de documentation :

✅ Utiliser les outils VS Code

edit (en mode agent) : createDirectory, createFile, editFiles...
read : read_file, text_search, problems, terminalLastCommand...
search : changes, codebase, file_search, list_directory, searchResults, textSearch, usages...
et tout autre outil disponible

Permet à l'utilisateur de suivre l'avancement, visualiser les modifications via diff et revert si nécessaire.

Si les outils sont indisponible ou les fichiers semblent hors workspace, persévérer d'abord (les fichiers sont accessibles par les outils vscode), puis l'indiquer à l'utilisateur plutôt que d'utiliser des commandes terminal, de copier-coller du contenu ou de lui indiquer la marche à suivre lui-même.

❌ Ne pas utiliser

cat > pour créer des fichiers complets
echo pour append du contenu
Édition manuelle via terminal

5. Informations du serveur, pas encyclopédie¶

Ne pas inclure des informations générales qui ne sont pas spécifiques au serveur documenté.

Tabler sur la capacité de l'utilisateur à rechercher des informations générales en ligne ou via des commandes shell.

Si nécessaire, lier vers des ressources externes ou des documentations officielles.

6. Affiner plutôt que d'ajouter¶

Préférer améliorer une page existante plutôt que d'en créer une nouvelle
Supprimer les infos obsolètes plutôt qu'ajouter des versions

Structure Pages¶

Longueur¶

Idéal : 150-200 lignes
Maximum : 300-400 lignes
Si >300L : Synthétiser selon les règles, et s'il reste suffisemment de contenu pertinent fragmenter en sous-pages

Titres¶

Maximum : 4-5 niveaux de titres par page
Structure typique :
- # Titre page (1 seul)
- ## Sections principales (3-4)
- ### Sous-sections (si nécessaire)

Organisation¶

Préférer :

Pages courtes
Liens entre pages
Pages index pour navigation

Éviter :

Pages monolithiques
Tout-en-un sans structure

Pages Index¶

Chaque dossier doit avoir un index.md :

Vue d'ensemble du sujet
Liens vers contenu détaillé

Contenu¶

Commandes¶

Toujours fournir commandes testées et fonctionnelles :

## Vérifier Backups PBS

\`\`\`bash

# État backups récents

pct exec 102 -- proxmox-backup-manager task list --limit 10

# Espace datastore

df -h /mnt/pve/pbs-datastore/datastore/
\`\`\`

Configurations¶

Référencer fichiers de config avec leur path :

## Configuration MergerFS

**Fichier:** `/etc/fstab`

**Options actives:**

- `cache.files=partial`
- `dropcacheonclose=true`
- `category.create=mfs`

Voir [mergerfs](mergerfs.md) pour détails options.

Éviter Info Obsolète¶

❌ Éviter mentions qui deviennent rapidement fausses :

"Actuellement nous utilisons..." → utiliser présent affirmé
"Version 3.4.8-2" si change souvent → "Version installée: proxmox-backup-manager --version"
Dates spécifiques de déploiement
"En cours de..." ou "bientôt"

Liens vers des pages¶

Utiliser des liens relatifs quand les pages sont reliées (même dossier ou sous-dossiers), utiliser des liens absolus pour les autres.
Utiliser des titres explicites et des liens propres (pas "page.md")

✅ OK :

Voir configuration [MergerFS](/storage/mergerfs) pour détails.

❌ PAS OK :

Voir configuration [mergerfs.md](../storage/mergerfs.md) pour détails.

Après un changement de la documentation¶

Comparer les changements à chaque règle de CONTRIBUTING et corriger si nécessaire
Faire une recherche de tous les fichiers pour les termes modifiés (grep_search) et vérifier que les changements sont cohérents dans toute la documentation
Mettre à jour la navigation si des pages sont ajoutées/supprimées
Corriger les liens internes si des pages sont déplacées ou renommées