Rules: Writing Style

# Writing style

Write all English prose in **ASD-STE100 Simplified Technical English**. This applies to two groups
of text.

- **Text you commit.** Documentation, README files, agent instruction files, code comments,
  docstrings, commit messages, PR descriptions, error strings, log messages, CLI help text, and
  user-facing UI copy.
- **Text you send to the reader.** Chat replies, explanations of your changes, summaries of your
  work, plans, and clarifying questions. Do not relax the rules because the text is temporary.

Apply the rules to English prose only. They do not govern identifiers, config keys, file paths,
commands, or code.

## Core rules

- **One word, one meaning.** Use one term for one thing, and one thing for one term. Do not
  substitute synonyms for variety. If a thing is a "button" in one sentence, it is a "button" in
  every sentence.
- **Take terms from the project.** Use the name that the codebase, the framework, or the domain
  already uses. Do not invent a simpler name for a thing that has a name. Technical names and
  technical verbs are always allowed.
- **Sentence length.** 20 words maximum in a procedure. 25 words maximum in a description.
- **One instruction per sentence.** Split a compound step into separate sentences or into a
  vertical list. Use the imperative for instructions: "Run the test suite before you commit."
- **Active voice.** Write "the compiler resolves the import", not "the import is resolved by the
  compiler".
- **Simple tenses.** Use the present, the simple past, or the simple future. Avoid `-ing` forms
  unless they are part of a technical name.
- **Keep the small words.** Do not drop articles (`the`, `a`) or relative pronouns (`that`,
  `which`) to save space.
- **Short noun clusters.** Three nouns maximum in a row. Break up "database connection pool
  timeout" into "the timeout for the database connection pool".
- **Paragraphs.** Six sentences maximum. Put the topic sentence first.
- **Lists.** Use a vertical list for three or more parallel items. Do not hide a procedure inside a
  paragraph.
- **Warnings first.** Start a warning or a caution with the command, then give the reason. Write
  "Stop the server before you edit the config. An open handle corrupts the file."

## Rules for specific text

- **Comments and docstrings.** Give the reason for the code, not a second copy of the code. Use one
  sentence if one sentence is enough. Start a docstring description with a verb in the present
  tense: "Returns the parsed value."
- **Commit messages and PR descriptions.** Start the subject line with an imperative verb. State
  what changed. Then state why it changed.
- **Error strings and log messages.** Name the thing that failed. Give the cause if you know the
  cause. Give the next action if an action is available.
- **Questions to the reader.** Ask one question at a time. Keep the question under 20 words. Give
  the options if the options are known.

## Limits

- Apply the rules to text that you write or that you must change for another reason. Do not rewrite
  unrelated prose only to make it conform.
- Do not change quoted text, third-party content, license text, or generated files.
- Follow the local convention if a project defines its own style guide. That guide wins where the
  two guides disagree.

Write for a reader who has technical knowledge but limited English. Clarity is more important than
tone.