Gabarit de page

En bref
Niveau : référence
Durée de lecture : 4 minutes
Prérequis : aucun

Pourquoi un gabarit ?

Toutes les pages techniques suivent le même plan. Le lecteur sait où trouver le principe, les commandes et les pièges, quel que soit le livre. Cette page décrit ce plan et les règles d'écriture.

Le plan d'une page

Ordre	Élément	Contenu
1	Titre	Un titre de niveau 1, court et orienté tâche
2	Encadré Information « En bref »	Niveau, durée, prérequis, niveau de test
3	« X, c'est quoi ? »	Le principe en quelques phrases
4	Tableau Composant / Rôle	Les éléments en jeu et leur rôle
5	Schéma en une ligne	Le flux de bout en bout, en gras, avec des flèches
6	Contraintes ou étapes	Liste numérotée
7	Fichiers et commandes	Blocs de code commentés
8	Pièges	Les erreurs rencontrées et leur correction
9	Vérification	Comment confirmer que le résultat est bon
10	Page suivante	Un renvoi vers la suite logique

Les encadrés

Les encadrés sont créés avec le menu Légendes > Informations de l'éditeur BookStack. Ils servent à deux usages :

L'encadré « En bref », placé juste sous le titre. Il contient quatre lignes (niveau, durée, prérequis, niveau de test), la première en gras comme titre.
Les remarques, placées là où elles sont utiles : une précision, une mise en garde légère, un renvoi. Elles s'écrivent directement, sans préfixe « Note ».

En bref
Niveau : intermédiaire
Durée : 30 minutes
Prérequis : un serveur Debian 12, accès SSH
Niveau de test : testé sur Debian 12 (voir « Niveaux de test »)

Les règles d'écriture

Règle	Détail
Ton impersonnel	Pas de « tu », de « vous » ni de « je » dans les pages techniques. La première personne est réservée aux pages d'accueil.
Une page, une tâche	Au-delà d'environ 1 500 mots utiles, la page est découpée
Termes anglais	Les termes techniques restent en anglais (playbook, reverse proxy, jail)
Code commenté	Chaque bloc de code est précédé d'une phrase qui dit ce qu'il fait et pourquoi
Données fictives	Noms, adresses et secrets viennent de la Charte
Honnêteté	Le niveau de test affiché correspond à ce qui a été fait

Une page de présentation de livre est unique : une seule page remplace les séries de pages génériques (« À quoi ça sert ? », « Pourquoi l'utiliser ? »…).

Vérifier une page avant publication

Le plan ci-dessus est respecté.
Aucun nom, aucune adresse ni aucun secret ne sort de la Charte.
Le niveau de test est exact.
Les blocs de code sont valides et commentés.
Les captures d'écran ne montrent aucune information réelle.

Page suivante : retour à la page Bienvenue, ou premier livre de l'étagère Base de connaissance.