Une étagère de livres n’est plus un programme de formation

En 2026, une simple bibliographie vieillit vite. Git, les contrôles automatiques et l’IA générative font partie du travail, tandis que les guides publics évoluent pendant l’année. Les livres restent utiles pour développer une pensée longue ; les guides vivants répondent mieux aux décisions actuelles sur le code, l’UI, la terminologie et les procédures.

Microsoft et Google maintiennent leurs guides, GitHub publie ses modèles de contenu, IBM expose ses standards de qualité et Diátaxis fournit une structure pratique des types de documentation.

Cinq guides vivants à garder ouverts

Source Point fort Idée pratique
Microsoft Voix, procédures, UI Phrases simples, voix active, actions directes
Google Developer docs, audience mondiale Conditions avant instructions ; éléments techniques en code
GitHub Docs Besoin utilisateur et structure Garder seulement le nécessaire, choisir un content type
IBM Évaluation qualité Séparer accuracy, completeness, clarity, organization et retrievability
Diátaxis Architecture Distinguer tutorial, how-to, reference et explanation

Comparer le même problème entre plusieurs traditions

Phrase faible : « Afin de terminer correctement l’opération, les utilisateurs doivent s’assurer que le dépôt a été initialisé avant de cliquer sur Create. »

Microsoft pousse vers « Initialisez le dépôt, puis sélectionnez Create ». Google peut placer la condition avant l’action : « Avant de sélectionner Create, initialisez le dépôt. » GitHub remet l’objectif en tête : « Pour créer le projet, initialisez le dépôt puis sélectionnez Create. » IBM vérifie en plus que le prerequisite est vrai et que le résultat est décrit. Diátaxis demande si cette procédure appartient à une page reference ou à un how-to.

Étudier un problème à la fois avec un exercice réel

Problème Comparer Exercice Résultat
Prérequis cachés Microsoft + Google Réécrire une procédure réelle Before/after + règle locale
API reference trop narrative Diátaxis + Google Séparer faits et scénario Reference claire + how-to
Terminologie variable Google + Microsoft Auditer 20 termes Mini-glossaire + règles lint
Review répétitif IBM + GitHub Séparer machine et jugement Checklist de review
Localisation difficile Google + IBM Réécrire deux pages ambiguës Exemples locaux

Transformer la lecture en compétence

Partez d’un défaut réel, comparez deux ou trois sources, reformulez la règle, changez une page puis testez-la avec un lecteur ou un SME. Si la solution se répète, ajoutez-la au style guide local ou à un contrôle automatisé. Le journal d’apprentissage conserve le texte initial, le changement et le résultat du review.

Livres encore utiles et éléments qui ont vieilli

Docs for Developers (2021) couvre très bien le cycle complet, mais précède la vague LLM actuelle. Developing Quality Technical Information (2014) reste excellent pour penser la qualité, même si le contexte de delivery est plus ancien. Every Page Is Page One (2013) aide encore à concevoir des pages accessibles directement depuis la recherche, mais il faut maintenant intégrer les réponses IA et les portails modernes. The Product is Docs reste utile pour la collaboration dans l’équipe produit.

Construire son style guide à partir de décisions testées

Un guide externe est une référence, pas une constitution. Quand le même terme provoque plusieurs débats, décidez localement. Quand les exemples API divergent, fixez un modèle. Conservez quatre champs : problème, décision, bon exemple et exception.

Champ Exemple
Problème log in, login et sign in décrivent la même action
Décision Utiliser sign in pour l’action utilisateur ; garder les noms techniques
Exemple “Sign in to the admin console.”
Exception Un champ API login reste login

Que faire cette semaine

Choisissez une page qui a déjà reçu une remarque réelle. Formulez le problème, comparez deux sources et produisez une version before/after. Montrez-la à une personne qui utilise la documentation et ne conservez la règle que si elle améliore le résultat. Une semaine donne ainsi une page meilleure et une décision testée.

Articles liés