Sentence structure
Apply ASD-STE100 to every sentence: caps by content type, simple tenses, active voice, and the rules that keep a sentence unambiguous.
Write for a reader who cannot ask
The aerospace and defense industry publishes ASD-STE100, a controlled language for technical writing. Issue 9, dated 15 January 2025, contains 53 writing rules in nine sections. The standard also carries a dictionary of about 900 approved words. Each word in that dictionary has one meaning and one part of speech.
Azion documentation follows the sentence rules of this standard because its readers match the standard’s target reader. Many readers work in a second language. No author is present to answer a question. Retrieval systems index these pages in sections and return one section, not the whole page. A sentence that follows these rules also translates to Brazilian Portuguese with less drift.
Match the sentence cap to the content type
ASD-STE100 sets stricter rules for procedures than for descriptions. Azion maps that split onto the four base forms.
| Content type | Mode | Sentence cap |
|---|---|---|
| Tutorial | Procedural | 20 words |
| How-to | Procedural | 20 words |
| Reference | Descriptive | 25 words |
| Explanation | Descriptive | 25 words |
A procedure gets the tighter cap because the reader executes each step under load. A step that the reader misreads becomes an action that fails. The caps count prose sentences only. Table cells, code, and command output are exempt.
Use simple tenses only
Write with the imperative, the simple present, the simple past, and the simple future. Do not build tenses with auxiliary verbs. Prefer the simple present for Platform Resource behavior, because the platform behaves the same way on every request.
- Before:
The build has been completed. - After:
The build is complete. - Before:
Firewall will block the request. - After:
Firewall blocks the request.
Use an -ing word only as a noun
Inside a sentence, an -ing word must be a noun or part of one, as in caching or request logging. Do not use an -ing word as a verb or as a trailing clause. A trailing clause hides who acts and when it happens.
- Before:
The function validates the token, returning an error when the signature fails. - After:
The function validates the token. When the signature fails, the function returns an error.
The same logic applies to task headings, which start with an imperative verb, not a gerund. The full rules are in Headings.
Limit noun clusters to three words
A stack of four or more nouns has no grammar between the words. The reader cannot tell which word modifies which. Break the cluster with prepositions. A Platform Resource name counts as one unit, so Real-Time Metrics spends one of the three slots.
- Before:
the request phase behavior execution order - After:
the execution order of the behaviors in the request phase
Keep the subject, the verb, and the articles
Do not drop words to shorten a sentence. A sentence without its subject, verb, or articles reads faster and means less. When a sentence runs long, split it into two sentences.
- Before:
Objects not cached are fetched from the origin. - After:
When an object is not in the cache, Azion fetches it from the origin.
Keep each paragraph on one topic
Write one topic per paragraph, in six sentences at most. Retrieval systems cut pages into chunks, and a two-topic paragraph splits badly wherever the cut lands. Each fragment then carries half of the meaning.
- Before: one paragraph that defines the cache key and then describes purge behavior.
- After: one paragraph for the cache key, and a second paragraph for purge behavior.
Connect each sentence to the one before
Each sentence continues the topic of the sentence before it: its subject is the subject of that sentence, or something that sentence introduced. When the topic moves on purpose, open the sentence with the word that names the move: Because, If, When, Otherwise, Each. A consequence names its cause in the same way, so the reader never has to supply the link.
- Before:
An Application can run serverless functions or act as a reverse proxy for your origins. An Application receives the requests of a Workload once that Workload's deployment sets that Application. A reverse proxy is a server in front of your origins. - After:
An Application can run serverless functions or act as a reverse proxy for your origins. A reverse proxy is a server in front of your origins. An Application receives the requests of a Workload once that Workload's deployment sets that Application.
Check the prose when a section moves
A section that changes place keeps its text and loses its context: what the reader had already met when they reached it. After a move, check five things, in English and in Portuguese:
- First use: each term the moved section uses is defined at or before its first use in the new order.
- A fact told twice in a row: two sentences that sat a section apart and now sit back to back say one fact twice. Keep the full sentence where the content type asks for it, and shorten the other.
- Words that point at a position:
above,below,earlier, and a step number still point at what they meant. - The joins: a move creates three new joins, above the moved section, below it, and where it used to be. Each one still reads as a sequence.
- The rest of the page: a sentence that lists the sections of the page follows the new order.
On the Applications overview, the request path moved above the rule structure, and its first sentence then repeated the definition block:
- Before:
Creating an Application routes no request to it: an Application receives the requests of a Workload only after that Workload's deployment sets that Application. - After:
Creating an Application routes no request to it: a Workload's deployment has to set that Application first.
Let the first sentences carry the section
Read alone, the first sentence of each paragraph and the bold lead-in of each bullet carry the point of the section, in order. A reader who skims reads only those. A first sentence that is a caveat, a pointer, or a negation that never says what happens instead leaves that reader with nothing.
In a compressed block of bullets, every sentence of a bullet stays on the topic of its lead-in. A fact on another topic opens its own bullet.
- Before:
Creating an Application serves nothing. - After:
An Application receives the requests of a Workload once that Workload's deployment sets that Application.
Introduce one new term per sentence
A sentence that coins two terms makes the reader learn both at once and keep them apart. Introduce one new term per sentence, and keep one name for each thing after that.
- Before:
Image Processor builds a new image, the derived image, from the original image on your origin, the source image. - After:
Image Processor builds each image it delivers from an image on your origin, the source image. The image it delivers is the derived image.
State the fact, not what does not happen
When the subject is a thing, a negation makes the reader rebuild the fact from what is missing. Write the fact instead: a negation that stands alone fails, and one that says in the same sentence what happens instead passes. A managed service says what the platform provides, not only what the reader no longer does.
- Before:
Nothing searches the values or lists the keys. - After:
You cannot search values or list keys: every read goes straight to a key. - Before:
It adds no object to your account and has nothing to turn on. - After:
It is available to every account and needs no activation or configuration.
Say what happens, not a judgment
A judgment such as wrong, bad, or unsafe leaves the reader to guess the behavior behind it. Describe the behavior, and the reader draws the conclusion.
- Before:
That copy is wrong for content that varies by cookie. - After:
Every visitor receives that same copy, even when the content varies by cookie.
Name the element, not its role
A role such as entry point, backend, or handler can mean several elements. Name the element that does the work.
- Before:
The entry point decides which code answers. - After:
The Workload forwards the request to the Application, which decides which rule answers.
Use a vertical list for a sequence
Format three or more steps, conditions, or alternatives as a numbered or bulleted list. A sequence inside one prose sentence forces the reader to parse the order and the actions at the same time.
Before:
Save the file, then run the build, and then deploy the application.
After:
- Save the file.
- Run the build.
- Deploy the application.
Use the same word for the same action
Pick one verb for one action and repeat it across the page. A rotation of synonyms tells the reader that each verb names a different action.
- Before:
Verify that the build passed. Then check that the deploy passed. - After:
Verify that the build passed. Then verify that the deploy passed.
The rule extends to the items of a list. When a later sentence restates a list, it keeps the words of the first one: add or remove a header, then add or filter headers, reads as two different capabilities.
When a sentence describes a control in the Console, use the label that the Console shows. Do not improve on the vocabulary of the interface. When an interface string implies a fact, state the fact first, then quote the string as its source. A quoted string alone leaves the reader to derive the rule.
ASD-STE100 pairs its rules with an approved dictionary. Rules 1.5 and 1.12 of the standard let a project approve its own technical names and technical verbs. Azion uses that allowance: the approved vocabulary is in Word choice and in Documentation terminology.
Check your draft
Confirm each point before the page ships:
- Every tense is simple, and Platform Resource behavior uses the simple present.
- Every -ing word works as a noun or as part of a noun.
- Every noun cluster has at most three words, with a Platform Resource name counted as one word.
- Every sentence keeps its subject, its verb, and its articles.
- Every paragraph covers one topic in at most six sentences.
- Every sentence continues the topic of the one before, or opens with the word that names the move.
- Every section that moved defines its terms before their first use, repeats no fact of the block above it, and reads as a sequence at each join.
- The first sentences of the paragraphs and the lead-ins of the bullets, read alone, carry each section.
- Every sentence introduces at most one new term.
- Every sentence states the fact and what happens, and names the element instead of its role.
- Every sequence of three or more items is a vertical list.
- Every action keeps the same verb across the page, and every restated list keeps its words.
Sources
- ASD-STE100 official site: the standard, free to download.
- About STE: the 53 rules, the nine sections, and the Issue 9 date.
- Google developer documentation style guide: headings: the case against a gerund as the first word of a heading.