Aller au contenu

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 :

---
title: Onduleur (NUT)
created: 2026-11-09
updated: 2026-11-09
tags: nas, onduleur, nut
---
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 :

  1. un # Titre unique, explicite, qui peut être plus long que le title ;
  2. un ou deux paragraphes disant à quoi sert la page ;
  3. un tableau de contexte (hôte, adresse, chemin, date) quand il y a des valeurs à retrouver vite ;
  4. 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 !!! warning signale un piège réel, pas une décoration.
  • Blocs de code toujours titrés avec le chemin ou la machine :
```bash title="sur primidi"
docker compose up -d
```
  • 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

dans /opt/data/wiki
.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 :

status: obsolete

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.