Writing Homelab Documentation

Demande reçue : "Ajoute une page pour Proxmox"

1. Identifier le type de page (info / process / install-config)
2. Poser les questions de cadrage (voir Workflow)
3. Créer le fichier .md avec frontmatter au bon endroit dans l'arborescence
4. Rédiger en respectant la sémantique du type de page
5. Intégrer captures d'écran, tableaux, blocs de code
6. Livrer la page finale, prête à être commitée

Étape 1 — Déterminer le type de document

Toujours clarifier avant d'écrire :

• Information : description d'un concept, d'une architecture, d'un composant (pas d'actions à exécuter)
• Process : suite d'étapes récurrentes (sauvegarde, maintenance, procédure de dépannage)
• Installation/Configuration : mise en place d'un service précis, reproductible

Étape 2 — Collecter les informations brutes

Poser les questions pertinentes selon le type détecté :

• Quel service/composant est concerné ?
• Support physique ou virtuel ? (→ déterminre l'emplacement : serveurs-physiques/ vs machines-virtuelles/)
• Procédure disponible ? (tuto, script, commandes copier-coller)
• Documentation source utilisée (liens externes) ?
• Fichiers de configuration à inclure ?
• Dépendances avec d'autres pages existantes (à lier en cross-reference) ?

Écrire d'abord ces infos brutes dans le fichier (création du fichier + frontmatter minimal), sans polish. Ne pas bloquer l'utilisateur en attendant une réponse parfaite : itérer.

Étape 3 — Déterminer l'emplacement dans la structure

Respecter l'arborescence mkdocs existante (mkdocs.yml / nav). Règles par défaut :

• Machine physique → infrastructure/serveurs-physiques/<nom>.md
• VM → infrastructure/machines-virtuelles/<nom>.md
• Service applicatif → services/<categorie>/<nom>.md
• Page conceptuelle → concepts/<sujet>.md

Si ambigu, proposer l'emplacement plutôt que de demander — l'utilisateur valide ou corrige.

Étape 4 — Rédiger le frontmatter

YAML
---
title: <Nom du service/composant>
type: information | process | installation
status: draft | validé
tags: [proxmox, virtualisation, ...]
date_creation: 2024-01-15
date_maj: 2024-01-15
---

Étape 5 — Rédiger le contenu selon le type

Page Information :

• Contexte / objectif
• Architecture (schéma si possible, sinon description textuelle claire)
• Caractéristiques techniques (tableau)
• Liens vers pages process/installation associées

Page Process :

• Prérequis
• Étapes numérotées, chacune actionnable
• Points de vérification / rollback
• Fréquence si applicable (ex : sauvegarde hebdomadaire)

Page Installation/Configuration :

• Prérequis (matériel, logiciel, réseau)
• Étapes d'installation (commandes en bloc de code avec langage spécifié)
• Configuration post-installation
• Fichiers de config pertinents (en bloc de code, chemin en commentaire)
• Vérification / tests de bon fonctionnement
• Section Troubleshooting si pertinent
• Sources / liens de référence utilisés

Étape 6 — Intégrer médias et enrichissements

• Captures d'écran : ![description explicite](chemin/image.png), jamais de nom de fichier générique (image1.png)
• Convertir les listes de caractéristiques en tableaux Markdown dès que ≥3 éléments comparables
• Utiliser les admonitions MkDocs (!!! note, !!! warning, !!! tip) pour les informations critiques
• Blocs de code toujours avec langage spécifié (```bash, ```yaml, ```nginx)

Étape 7 — Passe de finalisation

• Relire pour cohérence terminologique avec le reste de la doc
• Vérifier les liens internes (cross-reference vers pages liées)
• Mettre à jour status: validé et date_maj
• Mettre à jour nav dans mkdocs.yml si nouvelle page

Progress:
- [ ] Type de document déterminé
- [ ] Informations brutes collectées et écrites
- [ ] Emplacement dans l'arborescence choisi
- [ ] Frontmatter rédigé
- [ ] Contenu structuré selon le type
- [ ] Médias/tableaux intégrés
- [ ] Relecture et mise à jour nav