Style Guide STE - ChristianPresley/zig-sdk GitHub Wiki

Style Guide (STE)

This page tells you how this project applies ASD-STE100 Simplified Technical English, Issue 91. The standard has a copyright. This page cites its rules by number and does not copy its text. The word lists of the Dictionary are the work of this project. The repository file docs/style/ste-profile.md is the source of this page.

Applies to: all prose of the project.

Surfaces

The profile applies to these texts:

  • The README and the other Markdown files in the repository.
  • Every page of the wiki.
  • Doc comments (/// and //!) in Zig source files.
  • User-visible messages in the SDK. The linter checks the .message = "..." string literals outside test blocks.

The profile does not apply to identifiers, commit messages, quoted text, licenses, fixtures and generated files. A generated file says "generated by zig build" in its first 512 bytes.

The linter

zig build lint-docs runs the linter with --strict and --string-literals on the prose of the repository. The tool is in tools/lint_docs/.

lint-docs [--format text|github|json] [--strict] [--string-literals]
          [--wiki-dir DIR] [--dictionary DIR] [--rule ID=off|warn|error] [PATH...]
Option What it does
--format The output format. github gives GitHub workflow commands. json gives one JSON object. In GitHub Actions the default is github.
--strict Every warning is an error. The build step and CI use this option.
--string-literals Also check the user-visible messages in Zig files.
--wiki-dir DIR Check the wiki clone in DIR. Links to wiki pages and the page template get checks too.
--dictionary DIR The directory of the word lists. The default is docs/dictionary.
--rule ID=off Disable a rule, or change its severity with warn or error. Use it only on your computer. CI does not disable rules.

Without a path and without --wiki-dir, the linter checks README.md, CONTRIBUTING.md, SECURITY.md, VERSIONING.md, the pull request template and the Markdown files in docs/. It also checks the Zig files in src/, tools/, conformance/, examples/ and bench/.

To check the wiki, run zig build lint-docs -- --strict --wiki-dir ../zig-sdk.wiki.

Rules that give an error

Rule What the linter checks
STE-1.1 Only approved words. The linter finds the words of project_word_list.txt. This file names the words that we do not use, with the replacement.
STE-4.2 No contractions.
STE-5.1 A procedural sentence has 20 words or less.
STE-6.3 A descriptive sentence has 25 words or less.
STE-6.6 A paragraph has six sentences or less.
STE-8.1 No semicolons.
STE-GR-6 No Latin abbreviations.
STE-GR-7 No gendered pronouns.
PRJ-6 The uppercase key words of RFC 2119 occur only in a quotation.
PRJ-8 A wiki page has the page template: the <!-- ste: ... --> marker and the Applies to line. Each citation has a reference, and each reference has a citation.
PRJ-9 A link has a target that exists: an anchor on the page, a file of the repository, or a wiki page and its anchor.
PRJ-10 No space or tab at the end of a line of a Markdown file.
PRJ-11 The Zig parser can parse the Zig file.

Rules that give a warning

Rule What the linter checks
STE-3.4 No complex verb forms, such as "has been" or "has stopped". Use the simple present, the simple past or the future.
STE-3.5 A word that ends in "-ing" is in ing_allowlist.txt.
STE-3.6 Active voice. A form of "be" and a past participle is a possible passive. participles.txt names the participles that tell a state.
PRJ-1 A sentence starts with an uppercase letter, a number, code or a name from abbreviations.txt.
PRJ-2 An abbreviation is in abbreviations.txt.
PRJ-3 US spelling. spelling_us.txt names the British spellings.
PRJ-4 One term for one concept. synonyms.txt names the terms that we do not use.
PRJ-5 No phrasal verbs from phrasal_verbs.txt.
PRJ-7 The summary of a doc comment ends with a period. The summary is the text before the first empty line, list or code block.

With --strict, every warning is an error.

What the linter does not check

The Markdown pre-pass removes these parts before the rules run:

  • Code blocks, code spans and HTML comments. A code span counts as one word.
  • Headings, and the header row of a table.
  • Quotations: a line that starts with >. Quotations are the only exemption in the text.
  • Footnotes and link reference definitions.

Text in double quotes counts for the length of the sentence only. The other rules ignore it. Use double quotes for the title of a document and for a short quotation of the specification.

The text of a link to a wiki page that has the page name, such as [Getting Started](Getting-Started), is a name. The rules ignore it.

Word count

The linter counts words as the standard tells in rules 8.4 to 8.7. Text in parentheses, numbers, hyphenated words and code spans count as one word.

Procedural and descriptive text

A section with a heading that starts with "Steps", "Procedure" or "How to" is procedural. Items of a numbered list are procedural. A page with the marker <!-- ste: procedural --> is procedural. All other text is descriptive.

RFC 2119 words

The MCP specification uses the words of RFC 21192. In our prose we write them like this:

Specification word Our prose
MUST must
MUST NOT must not
SHOULD We recommend that ...
MAY can

Use the uppercase words only inside a quotation of the specification.

Technical nouns and technical verbs

The project declares its technical nouns in docs/dictionary/technical_nouns.txt and its technical verbs in docs/dictionary/technical_verbs.txt. Use one term for one concept. Do not use a technical noun as a verb.

The dictionary

The files in docs/dictionary/ are the project dictionary:

File Contents
technical_nouns.txt Technical nouns.
technical_verbs.txt Technical verbs.
approved_verbs.txt General verbs that our prose uses.
restricted_words.txt Approved words with one meaning in this project.
project_word_list.txt Words that we do not use, with the replacement (STE-1.1).
synonyms.txt Terms that we do not use, with the project term (PRJ-4).
phrasal_verbs.txt Phrasal verbs with a replacement (PRJ-5).
spelling_us.txt British spellings with the US spelling (PRJ-3).
abbreviations.txt Abbreviations and names with a fixed case (PRJ-1, PRJ-2).
participles.txt Past participles that tell a state (STE-3.6).
ing_allowlist.txt Approved words that end in "-ing" (STE-3.5).

zig build gen-dictionary writes the lists as one page to docs/generated/dictionary.md. The Dictionary page of the wiki is a copy of that page.

Page template

Every wiki page has this shape:

  1. A level-one title.
  2. An HTML comment with the mode (descriptive or procedural), the review date and the versions it applies to.
  3. A summary of six sentences or less.
  4. An Applies to line.
  5. Sections. A citation is a superscript number that links to the References section.
  6. A References section. Each item has an anchor and links to a key of the Bibliography.

The linter checks the marker, the Applies to line, the citations and the references (PRJ-8). A page with a name that starts with _, for example the sidebar _Sidebar.md and the footer _Footer.md, does not have the template.

References

  1. STE100: ASD-STE100 Simplified Technical English, Issue 9.
  2. RFC2119: "Key words for use in RFCs to Indicate Requirement Levels".

zig-sdk uses the Apache License 2.0. The wiki uses the project profile of ASD-STE100 Simplified Technical English. The Bibliography lists the sources.

⚠️ **GitHub.com Fallback** ⚠️