Sentence structure

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 9 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 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.

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 product 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 product 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.

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:

1. Save the file.
2. Run the build.
3. 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.

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.

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 product 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 product 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 sequence of three or more items is a vertical list.
• Every action keeps the same verb across the page.

Sources

• ASD-STE100 official site: the standard, free to download.
• About STE: the 53 rules, the 9 sections, and the Issue 9 date.
• Google developer documentation style guide: headings: the case against a gerund as the first word of a heading.