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.