Ryuketsukami/explication-simple

Compétence d'Explication Simple (CES)

Donnez d'abord la réponse, en mots simples. Ajoutez de la profondeur par couches que le lecteur peut sauter. Ne sacrifiez jamais la vérité pour la simplicité.

La forme : réponse, puis mécanismes, puis détails

Ordonnez l'explication selon ce dont le lecteur a besoin, non selon la façon dont vous l'avez apprise :

1. La réponse. Une ou deux phrases simples qui répondent directement à la question ou énoncent le point. Un lecteur qui s'arrête ici a une image correcte — plus petite, jamais erronée.
2. Comment et pourquoi. Les mécanismes derrière la réponse : la cause, la structure, la règle en jeu.
3. Les détails. Nombres, paramètres, cas limites, exceptions, preuves. La partie que la plupart des lecteurs sautent — et celle qui doit rester présente lorsqu'on revient la chercher.

Tenez la forme avec ces règles :

• Terminez chaque couche avant de commencer la suivante. N'entremêlez jamais résumé et détails.
• Rendez les couches visibles et sautables : un saut de paragraphe, un début en gras, une étiquette, un titre ou un expandeur lorsque le support le permet.
• Une réserve qui modifie la réponse appartient à côté de la réponse. Les risques de sécurité, les pertes de données, les changements cassants et les coûts réels ne se placent jamais dans une couche inférieure.
• Les étapes suivent l'ordre des dépendances. Disposez le texte autour d'une procédure — résultat et préconditions d'abord, puis les étapes numérotées, puis les cas d'échec — mais ne réordonnez jamais les étapes par importance.
• La profondeur suit la question. Une réponse dans un chat peut nécessiter une couche ; un document de conception peut en demander quatre. N'allongez jamais une explication pour remplir la forme.

Les mots

• Commencez par l'acteur et le verbe : « le cache retourne des données obsolètes », pas « des données obsolètes peuvent être retournées ».
• Utilisez un nom pour une chose, le même nom à chaque fois. Changer de nom donne l'impression de changer de chose.
• Préférez le mot court et courant : utilisez, commencez, aidez, montrez — pas employer, initier, faciliter, démontrer.
• Mettez une idée par phrase. Traitez 20 mots comme un plafond ; divisez plutôt qu'empilez les propositions.
• Mettez la condition avant l'action : « Si la build échoue, vérifiez le fichier de verrouillage » — pas l'inverse.
• Définissez un terme en une demi-phrase là où le lecteur le rencontre. N'amoncelez pas d'arrière-plan.
• Transformez les noms abstraits en verbes : « analysez le journal », pas « effectuez une analyse du journal ».
• Coupez les remplissages, intensificateurs et éloges vides : très, robuste, fluide, puissant, complet, « il est important de noter ».
• Donnez des nombres au lieu d'adjectifs : « de 40 s à 6 s » bat « nettement plus rapide ».

Le socle : simple, jamais moins vrai

• Gardez chaque fait, nombre, avertissement et réserve. Simplifier déplace les détails dans une couche inférieure ; cela ne les supprime jamais.
• N'inventez pas d'exemples, de preuves ou de confiance que la source ne possède pas. Quand quelque chose est inconnu, dites-le clairement.
• Traitez une analogie comme un pont, pas une preuve. Si le lecteur doit s'y appuyer, dites où elle se brise.
• Quand simplicité et exactitude s'affrontent, l'exactitude gagne — puis continuez à travailler pour rendre la version exacte simple.

Exemple

Avant — vrai, complet, difficile à utiliser :

Une transaction est une séquence d'instructions traitée comme une unité de travail indivisible — initiée implicitement à la première instruction et terminée par COMMIT ou ROLLBACK — une construction importante car de nombreuses opérations multi-étapes ne sont correctes que lorsqu'elles sont exécutées atomiquement.

Après — les mêmes faits, en couches :

Une transaction est un groupe d'instructions qui réussissent ou échouent toutes ensemble.

Elle commence à la première instruction et se termine par COMMIT (conserver les modifications) ou ROLLBACK (les annuler).

Le regroupement est important car certaines opérations ne sont correctes que dans leur ensemble : un transfert qui débite un compte sans créditer l'autre laisserait l'argent manquant.

Vérifiez avant de livrer

• La première phrase répond-elle à la question ?
• Le lecteur peut-il s'arrêter après n'importe quelle couche et rester correct ?
• Les avertissements et les réserves qui changent la réponse se trouvent-ils dans la couche supérieure ?
• Y a-t-il un endroit où un mot plus court et plus courant conserverait le sens ?
• Chaque fait, nombre et réserve a-t-il survécu ?