jonshaw199/decision-doc-quality

Qualité des documents de décision / options

Utilisez ces règles pour chaque document de décision technique, d'étude ou d'options qui propose des choix et une recommandation. Le lecteur est un collègue occupé sans aucun contexte ; le document doit pouvoir être parcouru, être simple et prouvable.

Public : supposez un contexte nul

• Supposez que le lecteur ne connaît rien du savoir informel de l'équipe. Glosez ou liez chaque terme, acronyme, nom de service, outil et modèle d'utilisation (par exemple, CDC, Debezium, Kafka, SNS, SQS, outbox, réplication logique, Temporal). « Personne ne sait ce que tout cela signifie. »
• Expliquez ce qu'est une chose et ce qu'elle fait en termes simples avant de vous y référer. Préférez une phrase simple + un lien plutôt que du jargon seul.
• N'ajoutez pas de section glossaire séparée sauf si demandé ; liez les termes en ligne à la place.

Style d'écriture

• Commencez par l'essentiel (BLUF). Énoncez d'abord le point principal, puis les détails.
• Soyez concis. Les phrases uniques sont meilleures que les paragraphes. Si une section ressemble à un mur de texte, coupez-la. Personne ne lit les longs documents.
• Langage simple. Pas de contenu généré par IA, pas de remplissage qui « sonne bien », pas de narration de l'évolution du document, pas de défense de votre raisonnement à l'intérieur du document (par exemple, ne dites jamais « preuve directe, pas de théorie »).
• Pas de tirets cadratins (—) nulle part. Pas de majuscules pour l'emphase (utilisez le gras). Pas de numérotation décorative ou de séparateurs middot qui ressemblent à du contenu généré par machine.
• « Nous » pour le travail que l'équipe ferait ; « Je » pour l'opinion/le penchant de l'auteur. Gardez-les distincts.

Structure

• Recommandation / TL;DR en haut. Quelques lignes : le penchant, les raisons clés (sous forme de puces), présenté comme un premier avis sur un document vivant qui changera après les commentaires de l'équipe. Rendez explicites l'indifférence et la flexibilité lorsqu'elles sont réelles ; indiquez toujours une préférence et pourquoi.
• Un bloc repliable (toggle) par option. La ligne réduite montre une courte étiquette + un résumé en anglais simple d'une ligne. À l'intérieur : un diagramme simple, comment cela fonctionne, ce qui est réutilisé (avec des liens de preuve), ce qui est entièrement nouveau, échelle/compromis, et une petite esquisse de code ou de configuration. Gardez la surface parcourable.
• Gardez les sections parallèles (la cohérence n'est pas facultative). Les options/outils/candidats sont des frères, donc chacun DOIT suivre le même modèle : les mêmes sous-titres de section dans le même ordre, la même présence de diagramme / média / esquisse de code, la même profondeur. Fixez le modèle une fois (à partir de la section la plus forte) et appliquez-le à tous ; lorsque vous ajoutez ou modifiez une section, réalignez les autres. Ne laissez jamais chaque section dériver dans sa propre forme ; une structure divergente semble bâclée et va à l'encontre du but même (comparaison côte à côte facile). C'est un mode d'échec récurrent : vérifiez-le avant de partager.
• Regroupez les options par un seul axe clair (par exemple, quand quelque chose se produit, ou comment). Ne mélangez jamais deux axes en un seul regroupement et ne créez pas de catégories fausses-frères qui se chevauchent. Si une chose est un détail d'implémentation d'une autre option (un exécuteur, un emplacement de destination), intégrez-la, ne la listez pas comme un frère.
• Illustrez le noyau partagé/le plus difficile, pas seulement les options, avec son propre schéma (gérez le cycle de vie complet, par exemple, création/mise à jour et suppression).
• Diagrammes (mermaid) pour l'illustration ; gardez-les précis (ne dessinez pas une table comme une base de données séparée, etc.).
• Terminez par une invitation aux commentaires (« Autres idées ? ») ; ne terminez jamais brusquement.
• Gardez les métadonnées minimales, seulement ce qui est souhaité (souvent juste le lien du ticket). Supprimez les lignes de statut/coquilles vides que l'auteur ne souhaite pas.

Exhaustivité des options

• Listez les options de manière exhaustive, pas seulement les deux ou trois habituelles. Les vrais problèmes en ont beaucoup ; incluez aussi celles qui sont clairement mauvaises pour que tout le champ soit visible (étiquetez-les comme faibles/référence).
• Reconnaissez toujours la base de référence « ne rien faire » et énoncez sa conséquence.
• Recherchez des sources réelles (documentation, Stack Overflow, Reddit, références de fournisseurs/modèles) pour trouver les options et la terminologie correcte. Wikipédia seul est le choix paresseux par défaut ; trouvez la source primaire pertinente.
• Nommez correctement les modèles de conception établis et liez-les ; n'appliquez pas un nom de modèle à mauvais escient. Vérifiez que le modèle correspond réellement avant de le citer.

Preuve (la règle fondamentale)

• Chaque affirmation sur ce que le système possède déjà est étayée par un lien vers la preuve (fichier source + ligne, configuration d'infrastructure, ticket). Pas d'hypothèses, pas de généralités.
• Si une affirmation ne peut être prouvée par un lien, marquez-la comme non vérifiée plutôt que de la présenter comme un fait.
• Vérifiez en lisant le fichier/l'infrastructure réel(le) vous-même. N'affirmez pas le résultat d'un sous-agent comme un fait sans l'avoir lu ; distinguez « j'ai lu » de « un agent l'a rapporté », et indiquez le niveau de confiance lorsque cela est important.
• Ne faites jamais de revirement silencieux. Lorsqu'une vérification modifie une affirmation antérieure, dites ce qui était faux et pourquoi, et corrigez-le.
• Remettez en question la prémisse et vos propres conclusions lorsque c'est demandé ; revérifiez au lieu de défendre.
• Liez chaque identifiant, nom de fichier, ticket, PR et référence ; ne laissez jamais un identifiant nu que le lecteur doit chercher.

Contenu du document d'options

• Séparez le noyau dur partagé (le travail nécessaire quelle que soit l'option) des enveloppes/mécanismes qui l'entourent, et dites ce qui est le véritable effort et risque.
• Donnez les avantages et inconvénients, de manière fondée. Ne surestimez pas (« la majeure partie du travail et presque tout le risque » → adoucissez pour être précis).
• Notez ce que chaque option réutilise (qui existe déjà) par rapport à ce qui est entièrement nouveau.

Processus

• Faites des modifications minimales et ciblées. Ne réécrivez pas tout le document pour un petit changement.
• Pour un libellé sensible, montrez le brouillon dans le chat et itérez avant d'appliquer.
• Pour un message d'accompagnement/examen Slack : gardez-le incroyablement court et vraiment invitant (les gens sont occupés et ne voudront pas le lire) ; ne dites pas que c'est urgent ou pas urgent sauf si demandé ; préparez les relecteurs avec le cadre le plus utile unique.

Vérification finale

Avant de partager un document, vérifiez :

• Le point principal / la recommandation est en haut et court.
• Chaque affirmation « ce que nous avons » a un lien de preuve ; les affirmations non vérifiées sont étiquetées.
• Le jargon est glosé ou lié ; un lecteur sans contexte peut le suivre.
• Les options sont regroupées sur un seul axe clair, chacune repliable avec un résumé simple d'une ligne.
• Pas de tirets cadratins (—), pas d'emphase en majuscules, pas d'auto-narration, pas de contenu généré par IA.
• « Nous » vs « Je » utilisé correctement ; le penchant est énoncé mais la flexibilité est claire.
• Le document invite aux commentaires et ne se termine pas brusquement.