Use ASD-STE100

Use ASD-STE100 Simplified Technical English, Issue 9, January 2025, for descriptive technical prose. Read the ASD-STE100 site when you need the standard or its dictionary.

Orientation

Use this guide when you write or review technical prose. Keep exact source code, commands, paths, URLs, identifiers, requirement keywords, and scenario keywords unchanged.

Use one clear action

Use short sentences. Use active voice. Use present tense. Give one action in each step.

Use the same technical term for the same thing. Define a Beskid-specific term before you use it. Keep source code, command names, paths, URLs, and identifiers unchanged.

Mark the document authority

Add typed annotation metadata to every technical guide:

• State whether the page is informative or normative.
• Link to the authoritative standard, command reference, or source file.
• State what the page does not define.

For example:

Status: informative.
Authority: the Beskid Standard defines language behavior.
This page gives a verified workflow. It does not define a new rule.

Keep one source for each rule

Put normative requirements in openspec/specs/. Put public guidance in site/website/src/content/docs/docs/. Put tutorials in the Book. Put dated decisions in the blog.

Do not copy a technical rule into several documents. Link to the canonical document instead.

Check the page

Run the advisory review from site/website:

pnpm review:ste

The tool reports these candidate types with a file and line number:

Rule	Candidate
sentence-length	A rendered sentence has more than 25 words, including words across source line wraps.
passive-voice	A verb pattern can hide the actor.
unexplained-abbreviation	An uppercase abbreviation does not have an explanation or project approval.
article	An initialism can have an incorrect indefinite article.

The tool keeps headings, list items, table rows, and prose paragraphs as separate blocks. A lazy continuation stays in its list item. The tool removes MDX tags but keeps prose inside container tags. It excludes MDX expressions, frontmatter, fenced code, and requirement or scenario sections. Recursive review does not follow symbolic links.

The tool does not rewrite a file. It does not certify ASD-STE100 compliance.

Review each candidate manually against ASD-STE100 Issue 9. Rewrite the sentence when the report identifies unclear prose. Check links and commands after the rewrite.

The reviewer has an explicit list of approved Beskid technical terms. The list includes common project terms such as AOT, BSOL, CLI, LSP, OpenBao, and OpenSpec. Add a term only when the project uses it with one stable meaning.

Record a manual-review exception

Use an exception only after manual review. Put it directly before the affected prose line:

<!-- ste-review: ignore-next-line passive-voice,sentence-length -- Exact upstream quotation. -->
The quoted sentence stays unchanged.

Name only the applicable rules. Separate multiple rules with commas. Give a specific reason after --. The exception applies only to the next reviewable prose line.

Each named rule must suppress a candidate on that line. The tool reports an unused suppression as an error. It also reports an exception with no following reviewable prose.

Do not use an exception to hide a procedure error. Do not use one exception for a complete section.

Complete the review

Run pnpm test and pnpm build from site/website. Run OpenSpec validation after a normative change. Record the remaining candidate count as review evidence, not as a compliance score.

Limits

The review tool is advisory. It does not replace manual review and does not certify ASD-STE100 compliance. Apply an exception only to text that must remain unchanged.

Next steps

Return to Documentation authoring to check source ownership and the complete Docs gate.