Règles de rédaction du wiki¶
Ce wiki est un aide-mémoire technique personnel : il sert à refaire une installation six mois plus tard sans avoir à la redécouvrir. Une page qui ne permet pas de reproduire ce qu'elle décrit n'a pas atteint son but.
Le wiki est aussi lu par un assistant
Cet assistant (Karl) intervient régulièrement pour créer ou corriger des pages. Les règles ci-dessous sont ce qu'il applique. Les respecter garantit qu'une page écrite à la main et une page écrite par lui sont identiques de forme.
🗂️ Où ranger une page¶
| Section | Contenu |
|---|---|
nas/ |
le NAS lui-même (piNAS primidi), OpenMediaVault, partages NFS/SMB côté serveur, onduleur |
systeme/ |
Linux générique : Docker, paquets, comptes, sudoers, NIS, client NFS |
reseau/ |
ce qui relie les machines : DNS, Syncthing, remote gaming, sauvegardes |
services/ |
applications auto-hébergées en Docker |
medias/ |
Kodi, DVD, VHS, renommage de fichiers |
impression-3d/ |
OctoPrint, Simplify3D, lithophanies |
materiel/ |
une machine ou un périphérique précis |
divers/ |
ce qui ne rentre nulle part |
obsoletes/ |
page abandonnée, conservée pour référence |
En cas de doute entre « le NAS » et « le réseau » : nas/ décrit la machine et
son stockage, reseau/ décrit ce qui circule entre les machines. Un lien
croisé depuis l'autre page coûte une ligne et évite l'ambiguïté.
📛 Nommer un fichier¶
- Minuscules, tirets, sans accents ni espaces :
onduleur-nut.md,partage-nfs-serveur.md,windows-sharing.md. - Pas de préfixe de date, pas de majuscule, pas de
_. - Une page = un sujet. Au-delà de ~150 lignes, découper et lier.
🧱 Structure d'une page¶
Toute page commence par son en-tête :
| Champ | Rôle |
|---|---|
title |
affiché dans le menu de navigation et le sommaire de section |
created |
date de création, ne change plus |
updated |
à modifier à chaque retouche — seule mesure de fraîcheur |
tags |
deux ou trois mots-clés séparés par des virgules |
status |
obsolete uniquement pour les pages de obsoletes/ |
Puis, dans l'ordre :
- un
# Titreunique, explicite, qui peut être plus long que letitle; - un ou deux paragraphes disant à quoi sert la page ;
- un tableau de contexte (hôte, adresse, chemin, date) quand il y a des valeurs à retrouver vite ;
- les sections de contenu en
##.
Jamais deux # dans une page. Jamais de #### pour un titre de section : le
niveau #### disparaît de la table des matières et casse la cohérence du plan.
🎨 Emojis de section¶
Chaque ## de contenu porte un emoji pertinent, choisi pour le sujet, pas
pour décorer :
| Emoji | Usage |
|---|---|
| 🏗️ | architecture, schéma, comment les pièces s'assemblent |
| ⚙️ | configuration, paramètres, fichier de conf |
| 🛠️ | préparation, installation des prérequis |
| 🚀 | déploiement, commandes courantes, mise en route |
| 🧪 | vérifications, tests, diagnostic |
| 🌐 | réseau, accès, DNS |
| 💾 | stockage, disques, sauvegardes |
| 🔑 | secrets, mots de passe, authentification |
| 📦 | paquets, images Docker, installation |
| 🔧 | maintenance, réparation |
| 🎮 | usage, côté client |
Pas d'emoji sur ## Voir aussi, ni sur un titre purement bibliographique. Un
emoji ne remplace pas un mot : le titre doit rester lisible sans lui.
💬 Mise en forme¶
**gras**pour un mot-clé,*italique*pour une nuance,`code`pour une commande, un chemin, une valeur de configuration.- Encadrés :
!!! info,!!! tip,!!! warning— indentation de 4 espaces pour le contenu. Un!!! warningsignale un piège réel, pas une décoration. - Blocs de code toujours titrés avec le chemin ou la machine :
- Tableaux : uniquement les colonnes qui servent. Pas de colonne décorative.
- Liens entre pages en relatif :
[piNAS](../nas/pinas.md). Jamais d'URL absolue vers le wiki lui-même. - Titres de section en phrase, pas en Title Case.
✅ Vérifier avant de publier¶
.venv/bin/python migration/gen_nav.py # régénère nav + index de section
.venv/bin/mkdocs build --strict # doit sortir en 0, zéro warning
--strict transforme un lien mort ou une page absente de la navigation en
erreur : c'est ce qui empêche une page orpheline de passer inaperçue.
L'accueil (docs/index.md) n'est pas généré : il liste exhaustivement les pages
par thème et se met à jour à la main quand une page est ajoutée ou déplacée.
📜 Suivi en git¶
Un commit par intention cohérente, message en français décrivant le contenu :
Réseau : client Syncthing sur Bazzite
piNAS : primidi, Raspberry Pi + SATA Hat, 5x5To
OMV : architecture deux NAS, mergerfs piNAS+ReadyNAS
Pas de git add sélectif file par file quand la modification est cohérente :
git add -A puis git commit -m "…". Le message dit ce qui change, pas
« mise à jour » ou « corrections diverses ».
🗄️ Quand une page devient obsolète¶
Une page n'est jamais supprimée. Elle est déplacée dans obsoletes/ avec :
et le bandeau en tête :
!!! warning "Page obsolète"
Cette page n'a pas été mise à jour depuis plusieurs années et n'est
conservée que pour référence. Le contenu peut être inapplicable.
Le sommaire obsoletes/index.md affiche la dernière date de mise à jour lue
dans le front matter — d'où l'importance de tenir updated à jour.
📌 Deux règles qui priment sur les autres¶
Ne pas inventer. Une adresse IP, un chemin, une version, une date ne se devine pas. Si la valeur manque, l'écrire noir sur blanc (« adresse à confirmer ») plutôt que de mettre une valeur plausible qui sera crue plus tard.
Corriger à la source, pas en surface. Une valeur fausse se répète souvent à plusieurs endroits. Chercher toutes les occurrences avant de corriger, et vérifier les pages voisines qui pourraient porter la bonne valeur.