SysAdmin : doc claire en 4 blocs (Diátaxis + Wiki.js)

Pourquoi la doc SysAdmin devient vite ingérable (et comment s’en sortir)

Au début, la doc infra c’est simple. Un README dans le repo. Deux ou trois pages dans Notion. Quelques commandes épinglées dans Slack. Puis ça grandit. Un nouveau cluster. Une nouvelle équipe. Un audit qui arrive. Et là, sans prévenir, on se retrouve avec la doc la plus classique du monde.

Éparpillée partout.

Un bout dans des tickets Jira. Un autre dans un Google Drive oublié. Des procédures « temporaires » dans un canal privé. Des captures d’écran sans contexte. Et cette page wiki « installation de X » qui parle d’une version d’il y a deux ans, mais personne n’ose la toucher parce que ça marche encore en prod. Enfin, ça marchait.

Le vrai problème, ce n’est pas l’absence de doc. C’est la dépendance à « la personne qui sait ». Celle qui a déjà fait le rollback à 3 h du matin. Celle qui connaît l’ordre exact des commandes. Celle qui se souvient que le port 8443 n’est pas celui qu’on croit, parce que « c’est comme ça ». Et quand elle est en congé, ou qu’elle part, tout le monde improvise.

Et ça se voit vite dans le quotidien :

• MTTR qui s’allonge parce qu’on cherche l’info au lieu d’agir.
• Onboarding pénible, qui ressemble à un escape game.
• Erreurs en prod parce qu’une procédure mélange « pourquoi » et « quoi faire », donc on saute des étapes.
• Audits ISO, SOC2, ou juste une revue sécu interne qui devient un chantier, faute de traçabilité et de source unique.

La solution que je propose ici est simple, pas magique, mais vraiment efficace : structurer la doc en 4 blocs avec Diátaxis, puis l’implémenter proprement dans Wiki.js. L’objectif n’est pas d’écrire 200 pages. Au contraire. Un doc plus courte, plus trouvable, plus ensuite. Celle qu’on ouvre, qu’on exécute, et qu’on ferme.

Le déclic : arrêter d’écrire « un wiki fourre-tout »

Le piège classique, c’est la page hybride.

Une seule page qui commence comme un tuto (« installez ceci »), enchaîne sur une explication théorique (« TLS fonctionne comme... »), glisse une checklist de prod (« en fenêtre de maintenance... »), et finit par une mini table de référence (« ports, chemins, variables »).

Ça part d’une bonne intention. « Comme ça tout est au même endroit ». Sauf que personne ne lit une page de la même façon selon le contexte.

• Quand j’apprends, j’ai besoin d’un chemin, d’une progression.
• Quand je suis en incident, je veux une action, tout de suite, avec validation et rollback.
• Quand je dois décider, je veux comprendre les choix et les compromis.
• Quand je vérifie un détail, je veux une vérité factuelle en 10 secondes.

Mélanger tout ça, c’est condamner la page à devenir longue, floue, et difficile à maintenir. Et surtout, on n’ose plus la modifier.

L’objectif, au fond, c’est d’aligner chaque page sur un besoin utilisateur clair. Une intention de lecture. Diátaxis est une méthode simple pour y arriver.

Diátaxis, expliqué simplement : la doc en 4 blocs

Diátaxis, en une phrase : un cadre pour classer la documentation selon 4 intentions de lecture.

La carte est très nette :

• Tutoriels
• Guides pratiques (how-to)
• Explications
• Référence

Pour une équipe SysAdmin, ça change tout, parce que ça évite les pages « Frankenstein ». On gagne une meilleure recherche, une maintenance plus facile, et une doc qui sert en prod, pas juste « pour faire joli ».

Mini règle qui fait 80 % du boulot : une page = une intention principale. Si vous sentez que vous écrivez « et aussi », c’est souvent le moment de scinder.

Bloc 1 — Tutoriels : apprendre en faisant (pour les débutants)

Un tutoriel sert à former. Onboarder. Guider pas à pas, dans un environnement contrôlé. Ce n’est pas une procédure de prod, c’est un parcours d’apprentissage.

Caractéristiques typiques :

• progression claire (étapes qui s’enchaînent)
• prérequis explicites (accès, outils, droits, contexte)
• étapes vérifiables (checkpoints)
• résultat attendu (ce qu’on doit obtenir à la fin)

Exemples SysAdmin qui marchent bien :

• « Déployer un serveur Ubuntu durci »
• « Premier accès SSH + clés »
• « Installer l’agent de monitoring »

Ce qu’on ne met pas dans un tutoriel : les détails exhaustifs de paramètres (ça ira en Référence), et les discussions théoriques (ça ira dans Explications). Le tutoriel, lui, doit donner confiance. Tu suis, ça marche, tu comprends le minimum nécessaire.

Bloc 2 — Guides pratiques (how-to) : résoudre un cas précis rapidement

Le guide pratique sert à exécuter une action ciblée, souvent en prod ou préprod, avec un minimum de contexte. C’est la page qu’on ouvre quand on a déjà le droit de faire la manip, et qu’on veut la faire sans se tromper.

Format recommandé (simple, répétable) :

• objectif
• quand l’utiliser
• conditions et prérequis
• étapes
• validation
• rollback
• et idéalement, un mini « après » (surveillance post change)

Exemples :

• « Renouveler un certificat Let’s Encrypt »
• « Augmenter un volume LVM »
• « Restaurer un backup applicatif »
• « Rotation de logs »

Dans ces pages, les garde fous sont essentiels : risques, fenêtre de maintenance, impacts, commandes de vérification. Un how-to sans validation, c’est une recette sans minuteur. Ça finit mal.

Bloc 3 — Explications : comprendre le « pourquoi » (et éviter les erreurs)

Les pages d’explications donnent le modèle mental. Elles documentent les décisions d’architecture et les compromis. C’est souvent ce qui manque le plus, et pourtant c’est ce qui réduit le plus la dette sur la durée.

Contenus typiques :

• schémas et flux
• raisons d’un choix (et raisons d’avoir rejeté les autres)
• limites connues
• anti patterns
• conséquences opérationnelles (ce que ça implique en run)

Exemples :

• « Pourquoi on utilise un bastion »
• « Modèle de réseau (VPC/VLAN) »
• « Politique de sauvegarde 3-2-1 appliquée chez nous »

Lien direct avec la dette : ces pages réduisent les changements « au feeling ». Elles stabilisent les pratiques, et elles évitent les débats cycliques du type « on fait comme ça parce que… euh… ».

Bloc 4 — Référence : la vérité factuelle, consultable en 10 secondes

La référence, c’est la vérité vérifiable. On y vient pour confirmer un détail exact, sans narration.

Format qui marche :

• listes, tableaux
• snippets courts
• valeurs par environnement
• liens vers sources (repo, IaC, dashboards, tickets)
• champ « date de mise à jour » et « propriétaire »

Exemples :

• « Matrice des ports »
• « Inventaire des services »
• « Paramètres Nginx standard »
• « Variables CI/CD »

Règle importante : pas de storytelling ici. Un lecteur doit pouvoir scroller et trouver. Si on commence à raconter une histoire, on est probablement dans Explications.

Pourquoi Wiki.js est un bon choix pour appliquer Diátaxis (côté SysAdmin)

Wiki.js est un bon choix parce que c’est un wiki moderne, auto hébergeable, et pensé pour des équipes techniques qui vivent en Markdown. Pas besoin de convaincre une équipe infra de son intérêt, en général.

Points utiles côté SysAdmin :

• gestion des droits (RBAC), pratique pour séparer prod, sécu, ou docs internes sensibles
• historique et diff, donc traçabilité réelle
• recherche qui tient la route, surtout si la structure est cohérente
• éditeur Markdown, donc friction faible
• arborescence claire, plus tags, selon votre organisation

En infra, ces points comptent, parce que la doc n’est pas juste un « contenu ». C’est un outil de run. Il faut pouvoir contribuer à plusieurs, relire, savoir qui a changé quoi. Et ne pas avoir des edits invisibles dans un doc partagé.

Cadre de l’article : ici on parle organisation et méthode, pas d’une installation pas à pas de Wiki.js.

Mettre en place la structure Diátaxis dans Wiki.js (simple et maintenable)

Le meilleur moment pour définir une structure, c’est maintenant. Pas quand vous aurez 400 pages.

Concrètement :

1. créer 4 entrées principales, visibles
2. définir quelques conventions de nommage
3. créer des templates de pages
4. ajouter une page d’accueil « start here » qui oriente selon l’intention

Ce dernier point est sous estimé. Beaucoup de wikis échouent parce qu’on atterrit sur une homepage qui liste « catégories ». Là on veut une question simple : « tu es en train d’apprendre, de faire, de comprendre, ou de vérifier ? ».

Arborescence recommandée : 4 dossiers + des sous domaines

Structure de base, au niveau 1 :

• /tutoriels/
• /guides-pratiques/
• /explications/
• /reference/

Ensuite, vous avez des sous domaines transverses, typiques en SysAdmin : réseau, Linux, Kubernetes, sécurité, CI/CD. La tentation est de créer des dossiers par équipe, puis des sous dossiers par produit, puis… et la recherche devient un labyrinthe.

Approche simple :

• garder les 4 blocs au niveau 1
• classer le reste par tags, labels, ou sous pages cohérentes à l’intérieur de chaque bloc

Exemple :

• /guides-pratiques/linux/augmenter-volume-lvm
• /reference/reseau/matrice-des-ports

linuxkubernetessecuriteprodoncall

Templates prêts à l’emploi (1 par bloc)

Le template, c’est votre garde fou qualité. Pas pour faire « process ». Juste pour éviter la page vide où chacun écrit à sa façon.

Template tutoriel

• Objectif
• Prérequis
• Durée estimée
• Étapes
• Checkpoints (comment valider à mi parcours)
• Résultat final
• Aller plus loin (liens vers explications et référence)

Template guide pratique

• Objectif
• Quand l’utiliser
• Risques et impact
• Conditions (accès, fenêtre, version, environnement)
• Étapes
• Validation (commandes, métriques, logs)
• Rollback
• Post change (monitoring, tickets à ouvrir, métriques à suivre)

Template explication

• Problème ou besoin
• Options envisagées
• Choix retenu
• Implications opérationnelles
• Limites, anti patterns
• Schéma (si possible)
• Liens vers références et how-to liés

Template référence

• Tableaux et valeurs (par environnement si besoin)
• Sources de vérité (repo, Terraform, Ansible, CMDB, etc.)
• Date de mise à jour
• Propriétaire (owner)
• Notes courtes uniquement si nécessaire

Exemples concrets SysAdmin : transformer une doc « brouillon » en doc Diátaxis

Le plus parlant, c’est de prendre un sujet réel. Le genre de page qu’on a tous déjà vue.

Exemple 1 : TLS (la page unique qui devient 4 pages)

Vous avez une page « TLS sur nos services » qui mélange tout. On la découpe.

Tutoriel

• « Mettre en place TLS sur un nouveau service interne »
• Objectif : apprendre à intégrer TLS proprement dans un environnement contrôlé
• openssl s_client

Guide pratique

• « Renouveler un certificat (Let’s Encrypt ou interne) »
• Avec : conditions (prod, fenêtre), étapes, validation, rollback, et quoi surveiller après.

Explication

• « Chaîne de certificats : comment ça marche chez nous »
• Modèle mental : CA, intermédiaire, fullchain, erreurs fréquentes, pourquoi tel choix (AC interne vs LE), implications pour les clients.

Référence

• « TLS : emplacements, ports, commandes »
• Table : chemins des certificats par service, ports, conventions de nommage, snippets Nginx standard, liens vers la conf source.

Et là, magie très pragmatique : la prochaine fois que quelqu’un cherche « port TLS service X », il ne tombe pas au milieu d’un tuto. Il tombe sur une référence. Et inversement, le junior qui apprend ne tombe pas sur une table de ports sans histoire.

Exemple 2 : accès et comptes (le mélange explosif)

Même logique.

Tutoriel

• « Premier accès : bastion, SSH, clés, MFA »
• Apprentissage guidé, avec checkpoints.

Guide pratique

• « Révoquer un compte en urgence »
• Étapes courtes, validation, propagation, et rollback si c’est applicable.

Explication

• « Modèle RBAC : principes et raisons »
• Qui a accès à quoi, pourquoi, compromis, limites.

Référence

• « Groupes, politiques, liens utiles »
• Table des groupes, mapping vers environnements, liens vers IdP, procédures associées.

Règles de qualité qui font vraiment la différence (sans alourdir)

Quelques règles simples, qui donnent une doc utilisable en run.

• Écrire pour l’action : phrases courtes, commandes copiables, pas de blabla.
• Mettre la validation au centre : « comment je sais que c’est OK ? ». Tests, checks, métriques, logs attendus.
• Préciser l’environnement : prod/préprod, versions, chemins, dépendances. Une commande vraie en staging peut être dangereuse en prod.
• Ajouter « propriétaire + fréquence de revue » sur les pages critiques. Une référence sans owner, c’est une référence qui dérive.
• Liens internes : chaque how-to pointe vers son explication et sa référence associées. Pas besoin d’écrire tout partout, on relie.

Et un détail qui change tout : dans les guides pratiques, écrire aussi ce qu’il ne faut pas faire. Un anti pattern rapide. Deux lignes. Souvent ça évite l’incident.

Gouvernance légère : garder le wiki vivant sur le long terme

La gouvernance doit rester légère, sinon personne ne contribue. Mais elle doit exister, sinon le wiki meurt.

Un flux simple :

• créer
• relire (pair review si possible)
• publier
• revoir (mensuel ou trimestriel, selon criticité)

Rôles utiles :

• contributeurs : tout le monde
• relecteurs : quelques personnes par rotation, ou par domaine
• owners par domaine : réseau, sécu, plateforme, CI/CD

Wiki.js aide avec l’historique et les diffs. Utilisez le. Ça évite les modifications silencieuses, et ça rend les changements assumables.

Mesure pragmatique : regardez les pages « les plus vues » et « les plus modifiées ». Ce sont vos candidates prioritaires à renforcer, ou à refactor en Diátaxis si elles sont encore hybrides.

Conclusion : la doc claire, c’est (vraiment) un levier d’efficacité SysAdmin

Quatre intentions, quatre types de pages. Tutoriels, guides pratiques, explications, référence. Ce découpage rend la doc plus facile à écrire, plus facile à maintenir, et surtout plus facile à retrouver.

Démarrez petit. Choisissez un domaine, par exemple les sauvegardes, et migrez 5 pages. Pas plus. Créez les 4 dossiers, ajoutez les templates, puis refactor au fil de l’eau, quand vous touchez une page.

La meilleure doc n’est pas la plus longue. C’est celle qu’on retrouve en 10 secondes, et qui vous évite une erreur en prod. Le reste, franchement, peut attendre.

Questions fréquemment posées

Pourquoi la documentation SysAdmin devient-elle rapidement ingérable ?

La documentation SysAdmin devient vite ingérable car elle s'éparpille dans plusieurs outils (tickets Jira, Google Drive, Slack, wiki obsolète) et dépend trop de « la personne qui sait », rendant l'accès à l'information difficile, surtout lors d'absences ou départs.

Quels sont les problèmes courants liés à une documentation SysAdmin mal structurée ?

Les problèmes incluent un MTTR allongé, un onboarding compliqué, des erreurs en production dues à des procédures confuses, et des audits compliqués par le manque de traçabilité et de source unique.

Qu'est-ce que la méthode Diátaxis pour structurer la documentation ?

Diátaxis est un cadre qui divise la documentation en quatre blocs selon l'intention de lecture : Tutoriels (apprendre en faisant), Guides pratiques (how-to), Explications (pour comprendre), et Référence (détails factuels).

Pourquoi faut-il éviter les pages wiki hybrides dans la documentation SysAdmin ?

Les pages hybrides mélangent tutoriels, explications, checklists et références, ce qui rend la lecture confuse selon le contexte. Cela complique la maintenance et décourage les modifications, nuisant à l'efficacité de la doc.

Comment organiser efficacement une page de documentation selon Diátaxis ?

Chaque page doit avoir une intention principale claire : soit tutoriel, guide pratique, explication ou référence. Si plusieurs intentions apparaissent, il faut scinder en plusieurs pages distinctes pour faciliter la lecture et la maintenance.

Quels bénéfices apporte une documentation structurée avec Diátaxis et Wiki.js ?

Une doc plus courte, facilement trouvable et actionnable ; meilleure recherche ; maintenance facilitée ; réduction des erreurs en production ; onboarding simplifié ; audits plus efficaces grâce à une source unique et traçable.