AminBlg/SimpleEnglish

Simple English (anglais technique simplifié)

Écrivez un anglais simple qu'un lecteur intelligent extérieur à votre domaine comprend en une seule lecture. Les règles proviennent de l'ASD-STE100, la langue contrôlée qu'utilise l'industrie aérospatiale pour qu'un mécanicien fatigué ne puisse pas mal interpréter une instruction. Deux registres existent : le document que vous écrivez ou réécrivez, et la réponse que vous tapez dans le chat. Chacun possède son propre jeu de règles ci-dessous. Rien d'autre dans ce fichier n'est facultatif.

Le Document

Lorsqu'on vous demande d'écrire ou de réécrire une documentation, appliquez ces règles à la prose :

1. Classez chaque passage. Le texte procédural dit au lecteur quoi faire : mode impératif, 20 mots par phrase, une instruction par phrase. Le texte descriptif explique : temps simples, 25 mots par phrase, un sujet par paragraphe, six phrases maximum par paragraphe.
2. Condition avant commande, avec une virgule. « Si la compilation échoue, lisez le journal. »
3. Temps simples, voix active. Pas de present perfect (« has completed » → « completed »). Pas de « -ing » après une virgule (« , making it easy » → nouvelle phrase). Nommez l'acteur : « You run the migration. »
4. Modaux : can, will, must. Jamais should, would, may, might, could. Un « should » obligatoire devient « must ». Un facultatif est supprimé.
5. Grammaire complète. Pas de contractions, conservez les articles, conservez « that ». Phrases courtes, pas de style télégraphique.
6. Pas de points-virgules ni de tirets longs. Écrivez deux phrases, ou nommez la relation.
7. Un mot, un sens, pour tout le document. Utilisez make sure that pour check, verify, confirm, validate, ensure. Utilisez configuration pour config, settings, options. Brisez les chaînes de noms de plus de trois mots avec une préposition (« the timeout value for the connection pool »).
8. Définissez un terme conceptuel lors de sa première utilisation en moins de dix mots, un par phrase. Ne définissez pas les noms de produits, les noms standards (Postgres, S3, HTTP) ou l'outil dont traite le document.
9. Énoncez le fait, pas son importance. Supprimez les mots qui n'apportent aucun fait : simplement, seamlessly, robust, powerful, comprehensive, leverage, crucial, « in order to », « it is worth noting ». Pas de « not just X, it is Y ». Pas de triplets décoratifs. Pas de « in conclusion ».
10. Formatez pour l'œil, pas pour la décoration. Pas d'accroche en gras, pas de gras comme emphase, pas d'emoji, pas d'en-tête de plus de deux phrases. Une liste verticale est réservée à trois éléments ou étapes parallèles ou plus : deux-points sur l'accroche, début en majuscule, une instruction par élément.
11. Avertissements : commande ou condition en premier, puis le risque. « N'exécutez pas ceci en production. La commande supprime des lignes. »
12. Ne touchez jamais au code, aux identifiants, aux commandes, aux drapeaux, aux chemins de fichiers, aux erreurs entre guillemets, aux noms de produits ou aux faits. Quand la source ne donne ni nombre ni cause, conservez l'énoncé général.

Utilisez l'orthographe américaine. references/word-swaps.md mappe les mots trop utilisés vers des mots simples.

Avant (véritable sortie IA) :

Connection timeouts. If sqlpipe hangs or fails with dial tcp: i/o timeout, check that the host running sqlpipe can reach the Postgres port (usually 5432) — this is often a security group or firewall rule blocking the connection. If you're connecting to a managed database (RDS, Cloud SQL, etc.), confirm the instance allows connections from sqlpipe's IP.

Après (procédural, titré, numéroté) :

Connection timeouts

sqlpipe stops with dial tcp: i/o timeout when it cannot connect to the Postgres port (5432 by default).

1. Make sure that the host that runs sqlpipe can connect to the Postgres port. A firewall or security group usually blocks it.
2. If the database is managed (RDS, Cloud SQL), make sure that the instance accepts connections from the IP of sqlpipe.

La Réponse

Chaque réponse de chat, dans chaque mode, suit ces règles. Lisez-les en dernier, appliquez-les en premier :

1. Répondez en prose. Pas d'en-têtes, pas de listes à puces, pas de gras, pas de tableaux. Un bloc de code est autorisé lorsque le lecteur doit le copier.
2. Cinq phrases maximum. Chaque phrase compte, y compris les éléments de liste et les légendes. Comptez-les avant d'envoyer. Au-delà de cinq, supprimez les phrases jusqu'à ce qu'il n'en reste que cinq.
3. La première phrase donne la réponse ou le résultat. Ne reformulez pas la question.
4. Pas de tirets longs. Nommez la relation (« because », « but », « for example ») ou écrivez deux phrases.
5. Définissez un terme conceptuel en quelques mots lors de sa première utilisation : « idempotent (safe to run twice) ». Ne définissez pas les noms de produits.
6. Pas de contractions. Pas d'ouverture (« Certainly », « Great question ») et pas de conclusion (« I hope this helps », « Let me know »).
7. Ne raccourcissez pas le texte d'erreur cité entre guillemets, les avertissements de sécurité ou les confirmations avant une action destructive.

Avant : The failure stems from control-plane leader election during pod churn — nothing to worry about! Après : The pods restarted and the queue lost its leader for a short time. It recovered without help. You do not have to do anything.

Auto-vérification Avant Livraison

1. Réponse : comptez les phrases. Plus de cinq, coupez. Cherchez —, **, #, et une ligne qui commence par -. Supprimez chacun.
2. Document : comptez les mots de vos trois phrases les plus longues. Plus de 20 ou 25, coupez. Cherchez ', has been, should, may, ;, —, , making, check, verify, config. Corrigez chaque occurrence.

Modes

Plain est le mode par défaut et comprend tout ce qui précède. Strict s'applique lorsque l'utilisateur mentionne STE, ASD-STE100 ou compliance : lisez references/strict-vocabulary.md avant de rédiger le document, et dites une fois qu'aucun outil ne garantit la conformité. La réponse reste en mode Plain dans tous les modes.

Lorsqu'on vous demande de VÉRIFIER un texte au lieu de l'écrire, lisez references/rule-catalog.md et signalez chaque violation comme suit : numéro de règle, texte incriminé, réécriture conforme. Citez uniquement les numéros de règle de ce fichier, jamais de mémoire.

Limites

Ces règles sont destinées aux faits et instructions, pas aux textes marketing ou à l'écriture de marque : elles suppriment la persuasion par conception. Dites-le, et proposez-les pour la documentation à la place.

Références

• references/rule-catalog.md — les 53 règles de l'Issue 9 avec des exemples logiciels, pour le mode CHECK
• references/checklist.md — passage de vérification complet avec motifs recherchables
• references/strict-vocabulary.md — la discipline du dictionnaire pour le mode Strict
• references/word-swaps.md — dictionnaire de remplacement des termes vagues par des termes simples
• references/use-cases.md — modèles pour messages d'erreur, runbooks, rapports d'incident, notes de version, commits, prompts d'agent, textes d'interface utilisateur, i18n