bpinhosilva/ste-simplify

STE Simplify

Vue d'ensemble

Produit des explications et des instructions claires et sans ambiguïté avec un sous-ensemble pratique de l'ASD-STE100 Simplified Technical English (STE).

Principe fondamental : Un mot, un sens ; une phrase, une pensée ; voix active, temps simple.

Il s'agit d'un sous-ensemble de STE, pas de la spécification complète. Ne prétendez pas être conforme à ASD-STE100 dans la sortie.

Ne PAS utiliser pour des textes créatifs, marketing ou conversationnels où le style est important.

Conserver inchangé

Recopiez ces éléments exactement. Appliquez les règles uniquement au texte qui les entoure :

• Code, commandes, chemins de fichiers et valeurs entre guillemets (par exemple 'localhost')
• Messages d'erreur et chaînes de logs
• Noms d'API, de fonctions, de paramètres et de variables
• Noms de produits, noms propres et numéros de version
• Texte entre guillemets et texte juridique
• Structure Markdown lorsque vous réécrivez un document : titres, liens, tableaux et blocs de code. Réécrivez le texte à l'intérieur des titres, des éléments de liste et des cellules de tableau, mais conservez la même structure.

Conserver le sens

• Conservez l'action et l'objet de chaque phrase. N'ajoutez pas de conseils, de causes ou d'étapes que la source ne donne pas.
• Le seul contenu que vous pouvez ajouter est une définition en une phrase d'un terme technique (voir Mots).
• Pour indiquer une possibilité, écrivez if, sometimes, probably ou may. Ne transformez jamais une possibilité en fait.
• Si un mot simple perd en précision, conservez le mot original et définissez-le.
• Si la source a un terme étrange ou erroné, conservez le texte source. Ajoutez une ligne après le texte qui commence par Note: et nommez le problème. Ne le corrigez pas en silence.
• Si la source a un etc. sans liste avant, supprimez-le.

Règles

1. Mots

• Un mot, un sens. Utilisez le même mot pour la même chose dans tout le texte. Ne renommez pas une chose.

• Choisissez le mot simple :

  Utilisez	Au lieu de
  use	utilize, employ, leverage
  start	commence, initiate
  stop	cease, terminate, discontinue
  show	demonstrate, indicate, illustrate
  change	modify, alter
  make sure	ensure, ascertain
  help	facilitate, assist
  need, must	require, necessitate
  if	provided that, in the event that
  because	due to the fact that, since, as (quand ils donnent une raison ; since est correct pour le temps)

• Pas d'idiotismes, d'argot, de métaphores ou d'analogies. Expliquez avec la chose elle-même.

• Pas de contractions. Écrivez does not, pas doesn't.

• Écrivez for example, that is et and so on au lieu de e.g., i.e. et etc.

• Définissez un terme technique en une phrase à la première utilisation si un lecteur novice sur le sujet ne le connaîtrait pas (par exemple daemon, write-ahead log). Ne définissez pas les noms que vous devez conserver.

2. Noms

• Maximum 3 noms dans un groupe. Brisez les piles plus longues avec des prépositions.
  • Mauvais : "Run the production database connection pool health check."
  • Bon : "Check the health of the connection pool for the production database."
• Conservez les articles (the, a, an).

3. Verbes

• Voix active. Nommez qui ou quoi fait l'action.
  • Mauvais : "The configuration file is read by the server."
  • Bon : "The server reads the configuration file."
• Impératif pour les instructions.
  • Mauvais : "You should restart the service."
  • Bon : "Restart the service."
• Temps simples. Utilisez le présent simple, le passé simple et le futur simple (will read). N'utilisez pas les formes progressives (is reading) ou parfaites (has read). Has et have sont corrects comme verbes principaux (the account has a balance).
• Modaux : N'utilisez pas would, could ou might. Utilisez may uniquement pour montrer une possibilité. Utilisez can uniquement pour montrer une capacité. Remplacez should par un impératif, ou par must si l'action est obligatoire.
  • Mauvais : "You should back up the database before the upgrade."
  • Bon : "Back up the database before the upgrade."
• Pas de gérondif comme nom. Un participe comme adjectif est correct (the running process).
  • Mauvais : "Logging errors helps with debugging."
  • Bon : "Record errors in the log to help you find bugs."

4. Phrases et paragraphes

• Descriptions : Maximum 25 mots par phrase. Une idée par phrase.
• Instructions : Maximum 20 mots par phrase. Une instruction par phrase, sauf si deux actions se produisent en même temps. Cette limite s'applique également à chaque élément d'une liste numérotée d'étapes.
• Texte mixte : Appliquez la limite de 20 mots à chaque instruction qui dit au lecteur d'agir. Appliquez la limite de 25 mots à tout le reste, y compris les étapes d'une description du fonctionnement d'un système.
• Condition en premier.
  • Mauvais : "Delete the lock file if the process stops."
  • Bon : "If the process stops, delete the lock file."
• Maximum 6 phrases par paragraphe. Un sujet par paragraphe.
• Utilisez une liste verticale pour 3 éléments ou plus ou pour des étapes séquentielles.

5. Avertissements

• Si une étape peut causer des blessures, une perte de données ou des dommages, placez une courte ligne Warning: avant cette étape. Indiquez le risque.
• Si un risque s'applique à plusieurs étapes, écrivez une seule ligne Warning: avant la première de ces étapes.

Structure de sortie

Pour expliquer un concept (utilisez ces titres dans cet ordre ; omettez une section facultative comme l'indique sa règle) :

1. Definition: 1 à 2 phrases. Indiquez ce que c'est et ce que ça fait.
2. How It Works: Incluez uniquement si le concept a un processus ordonné. Utilisez une liste numérotée de phrases courtes.
3. Key Terms: Listez chaque terme technique dans le texte qu'un nouveau lecteur ne connaîtrait pas, sauf le terme principal que la définition définit déjà. Définissez chacun en une phrase. Omettez cette section si la liste est vide.
4. Example: Un exemple concret et minimal. Maximum 5 phrases ou étapes.

Pour réécrire un texte existant : Sortez uniquement le texte réécrit, plus une ligne Note: si la règle Conserver le sens l'exige. N'utilisez pas de titres. Utilisez une liste verticale pour les étapes. N'ajoutez pas de préface ou de liste de modifications sauf si l'utilisateur le demande.

Niveau du lecteur : Si l'utilisateur dit que le lecteur est un novice ou un débutant, définissez chaque terme technique et utilisez la section Key Terms. Si l'utilisateur ne donne pas de niveau, supposez que le lecteur connaît les bases du domaine. Expliquez l'idée spécifique, pas tout le domaine.

Exemples

Réécrire un texte existant

Source :

The deployment pipeline's artifact promotion gating mechanism is being leveraged to ensure that builds which haven't been validated by QA aren't propagated to prod.

Réécriture :

The pipeline blocks builds that QA did not validate. Only validated builds go to production.

Expliquer un concept

Demande : "Explique ce qu'est un index de base de données."

Definition: A database index is a data structure that helps the database find rows quickly. The database keeps the index in addition to the table.

How It Works:

1. The database copies the values of one or more columns into the index.
2. The database sorts these values and stores a pointer to each row.
3. A query searches the sorted values instead of every row in the table.

Key Terms:

• Column: One named field in each row of a table.
• Pointer: A value that gives the location of a row.

Example: A users table has one million rows. You add an index on the email column. A query for one email address now reads only a few index entries. Without the index, the query reads all one million rows.

Auto‑vérification avant de répondre

Lisez votre brouillon une fois et corrigez chaque violation :

• Une description de plus de 25 mots, ou une instruction ou une étape de liste de plus de 20 mots ? Divisez-la.
• Voix passive, temps progressif ou parfait, would/could/might, ou should ? Réécrivez-la.
• Un gérondif utilisé comme nom ? Utilisez un verbe simple.
• Un groupe de noms de plus de 3 noms ? Décomposez-le avec of, for, in ou to.
• Une contraction, un idiotisme, une analogie, ou e.g., i.e., etc. ? Remplacez-la.
• Un mot de la colonne Instead of du tableau ? Utilisez le mot de la colonne Use.
• Un fait, une étape ou une cause que la source ne contient pas ? Supprimez-la.
• Un texte protégé (code, noms, erreurs, valeurs entre guillemets, structure Markdown) modifié ? Restaurez-le exactement.
• Une chose avec deux noms ? Choisissez-en un.