simplified-technical-english

name

simplified-technical-english

description

Write clear, unambiguous English for technical documentation using Simplified Technical English principles (adapted from ASD-STE100 Issue 9). Use this skill whenever you write or review PR descriptions, commit bodies, READMEs, API documentation, ADRs, changelogs, runbooks, error messages, migration guides, code comments, or release notes — and any time the audience includes non-native English readers or machine translation. Also use it when the user asks for "STE", "ASD-STE100", "simplified English", "plain technical English", or asks to make documentation clearer, shorter, or easier to translate.

Simplified Technical English for software documentation

What this is

Simplified Technical English (STE) is a controlled natural language: a restricted vocabulary plus a set of writing rules. The authors built it so that a maintenance technician in Jakarta and one in Toulouse read the same sentence and reach the same conclusion. It removes ambiguity rather than making prose pretty.

This skill adapts those principles to software documentation. It is an independent adaptation, not the specification. Rule numbers such as [3.6] point back to ASD-STE100 Issue 9 (© ASD) for traceability. ASD holds the copyright on the official dictionary and on the rule text, so this skill does not reproduce them. See references/rule-index.md for the full tag list.

When to apply it, and when not to

Apply it to: PR descriptions, commit bodies, ADRs, READMEs, API reference, runbooks, incident postmortems, migration guides, error and log messages, changelogs, code comments, onboarding docs.

Do not apply it to: marketing copy, blog posts, conference talks, anything where voice and rhythm matter more than a single interpretation. STE deliberately sounds flat. The flatness is the point. STE is the wrong tool for persuasion.

Half-application is worse than none. If a document is in scope, apply the rules throughout it, not to selected paragraphs.

How to use this skill

Choose the workflow that matches the request.

The user writes something new. Apply the core rules below as you draft. Do not draft first and clean up after. Check the result against references/review-protocol.md, section "Self-check".

The user asks you to review or rewrite an existing text. Follow references/review-protocol.md. Report concrete edits, not general advice.

The text is a specific artifact (commit, PR, ADR, runbook, error message, changelog, code comment). Read references/artifacts.md for the rules that are specific to that artifact.

You need a word. Read references/word-substitutions.md. The table gives one short word for each meaning. It also lists the words that cause the most trouble in software writing.

You want a mechanical check. Run the linter:

python3 scripts/ste_lint.py --mode auto docs/**/*.md

The linter finds what a machine can find. It checks sentence length, semicolons, Latin abbreviations, contractions, passive constructions, nominalizations, phrasal verbs, long noun groups, and terminology drift. The linter cannot judge whether a sentence carries one idea. Run it as a first pass, then read the text yourself. See references/linter.md for the rule codes, the configuration file, and the suppression comments.

The two modes

Every technical text is either procedural (it tells the reader to do something) or descriptive (it tells the reader how something is). The rules differ. Decide which mode a block is in before you write it.

	Procedural	Descriptive
Verb form	Imperative [5.3]	Indicative. No imperative [6.x]
Max sentence length	20 words [5.1]	25 words [6.3]
Typical artifacts	Runbooks, setup steps, CONTRIBUTING	ADRs, architecture docs, API concepts

A README usually contains both. Switch mode per section, not per sentence.

Core rules

One idea per sentence, one topic per paragraph

Write short sentences with a clear structure [4.1]. In procedures, write one instruction per sentence, unless two actions must happen simultaneously [5.2]. In descriptive text, give each sentence a single subject and build up information gradually [6.1]. Each paragraph covers one topic [6.5] and holds no more than six sentences [6.6].

Avoid: The migration script reads the legacy table, maps the columns to the new
       schema, and then writes to the target database, but if a row fails
       validation it is written to a dead-letter table instead.

Write: The migration script reads the legacy table. It maps each column to the
       new schema. Then it writes the mapped rows to the target database. If a
       row fails validation, the script writes that row to the dead-letter table.

Active voice

Use the active voice [3.6]. Passive voice is allowed only in descriptive text, and only when the agent is genuinely unknown. Two examples hide who acted: "It was decided" and "the schema was changed". A reader of an ADR or a postmortem needs exactly that information.

Avoid: The connection pool was exhausted and the requests were rejected.
Write: The connection pool ran out of connections. The gateway then rejected
       the requests.

The action is a verb, not a noun

Do not turn actions into nouns [3.7]. Nominalization is the single most common failure in developer writing.

Avoid: Perform a validation of the payload before the invocation of the handler.
Write: Validate the payload before you call the handler.

Avoid: This change is a refactoring of the authentication module.
Write: This change refactors the authentication module.

Simple verb forms only

Use the infinitive, the imperative, the simple present, the simple past, the simple future, and the past participle as an adjective [3.2]. Do not stack auxiliaries into complex constructions [3.4]. No continuous tenses, no perfect tenses, no conditional chains.

Avoid: The worker will have been retrying the job for up to five minutes.
Write: The worker retries the job for a maximum of five minutes.

Avoid: This would have caused the cache to be invalidated.
Write: This invalidates the cache.

Use the -ing form only as a noun or as a modifier inside a noun [3.5]: "logging level" is correct, "the service is starting" is not. Write "the service starts".

Short noun groups

Write compound nouns of three words at most [2.1]. A longer chain forces the reader to guess how the words attach to each other. If a term genuinely needs more words, write it in full one time. Then define a short form, or hyphenate the parts that belong together [2.2].

Avoid: user session token refresh endpoint configuration
Write: the configuration of the token-refresh endpoint

Say the words you left out

Do not drop words to shorten a sentence, and do not use contractions [4.2]. Keep the conjunction "that". It marks where the main clause ends, and many languages cannot omit it [GR-1]. Keep articles and demonstratives before nouns [4.5].

Avoid: Make sure the flag's enabled before deploy.
Write: Make sure that the flag is enabled before you deploy.

Conditions come first

When the reader must know a condition before acting, put the condition at the start of the sentence and separate it with a comma [5.4]. The reader reaches a condition placed after the command too late.

Avoid: Delete the temporary volumes if the pipeline failed.
Write: If the pipeline failed, delete the temporary volumes.

Vertical lists for anything complex

Turn dense text into a vertical list [4.3]. Lists are easier to scan, and they make each item independently checkable. Keep list items parallel: same verb form, same structure.

No semicolons

The semicolon is not permitted [8.1]. It joins long sentences, and the rules exist to prevent long sentences. Write two sentences.

Hyphens bind words that are directly related [8.2], especially compound modifiers before a noun: read-only replica, zero-downtime migration, token-refresh endpoint.

Pronouns must be unambiguous

If a pronoun could point at more than one noun, repeat the noun [GR-3]. Pay special attention to "this" at the start of a sentence. It very often refers to a whole preceding clause, which the reader has to reconstruct [GR-4].

Avoid: The job writes to the queue and the consumer reads from it. This can fail.
Write: The job writes to the queue. The consumer reads from the queue. The write
       operation can fail.

No Latin abbreviations

Do not write e.g., i.e., etc., via, N.B., vs. [GR-6]. Write "for example", "that is", "and other ", "through", "note", "compared with".

One term per concept, always

Never use two different terms for the same thing [1.11], and keep terminology and style consistent across a document set [9.4]. In software this is the highest-value rule: if the entity is a tenant in the code, it is a tenant in the docs. It is not an "org", not a "workspace", not an "account".

Pick American spelling unless a house style says otherwise [1.14].

Gender-neutral language

Use neutral terms and constructions [GR-7]. Address the reader as "you". Use "they" for an unspecified person, or restructure to avoid the pronoun.

Word budget

Sentence limits are 20 words for procedures and 25 for descriptive text and for notes. When you count [8.4]–[8.7]:

• A number, or a number with its unit, counts as one word: 500 ms, 2 GB
• An abbreviation counts as one word: HTTP, JWT
• An alphanumeric identifier counts as one word: PR-4821, v2.1.0
• Quoted text counts as one word
• Anything in parentheses counts as one word
• A hyphenated word counts as one word
• Headings, titles, and labels count as one word
• In a vertical list, the colon ends the sentence for counting purposes

Vocabulary

STE's real enforcement mechanism is its dictionary: one approved word per meaning, and one meaning per approved word. ASD holds the copyright on that dictionary, so this skill does not reproduce it. Two things you can do without it:

1. Apply the principle. Choose the shortest common word that carries the meaning, and use it with only one meaning throughout the document.
2. Use references/word-substitutions.md in this skill. The table covers software writing, and it lists the terms that cause the most trouble in developer documentation.

If the project needs formal conformance (aerospace, defense, regulated industry), the licensed specification and a checker such as HyperSTE or Congree are required. This skill does not produce certified STE.

Warnings and cautions

For anything destructive or dangerous, use a signal word that matches the level of risk [7.1]. Start with the command or the condition [7.2]. Then explain the consequence [7.3]. In the source standard, a warning covers injury and a caution covers damage to equipment. The software equivalent:

• WARNING — irreversible data loss, security exposure, production outage
• CAUTION — recoverable damage, degraded service, cost impact

WARNING: Before you run this migration, take a full database snapshot. This
         migration drops the legacy tables and you cannot undo it.

Never bury a destructive consequence in the middle of a paragraph.

Review procedure

The short form is below. The full protocol, the report format, and the severity model are in references/review-protocol.md.

1. Split every sentence that carries more than one idea.
2. Convert passive constructions to active, and name the agent.
3. Convert nominalizations back into verbs.
4. Reduce complex verb constructions to simple tenses.
5. Cut noun groups down to three words or fewer.
6. Move conditions to the front of their sentence.
7. Replace ambiguous pronouns with the noun.
8. Remove semicolons and Latin abbreviations.
9. Unify terminology. List every concept that appears under more than one name.
10. Check sentence length against the 20/25-word budget.
11. Restore omitted "that", articles, and demonstratives.

If a word-for-word substitution does not produce a correct sentence, rewrite the whole sentence [9.1]. Do not force a bad sentence to survive.

Files in this skill

File	Use it when
references/word-substitutions.md	You need one approved word for a meaning
references/rule-index.md	You need the meaning of a [x.y] tag
references/artifacts.md	You write a commit, PR, ADR, runbook, or error message
references/review-protocol.md	You review or rewrite an existing text
references/linter.md	You run, configure, or extend ste_lint.py
scripts/ste_lint.py	You want a mechanical first pass

What this does not cover

STE says nothing about document structure, formatting, heading hierarchy, or information architecture. It governs sentences. Pair it with a style guide for everything above sentence level.