Writing style

The text of this site, the READMEs and the TSDoc comments follow the writing rules of ASD-STE100 Simplified Technical English as a style target. The rules make the text short, clear and the same for all readers, also for readers whose first language is not English. The project is not certified by ASD. The linter is an automated approximation of the rules. Refer to the writing standard for the background.

The main rules

• Write an instruction in 20 words or fewer, and a description in 25 words or fewer. A code span, a number with its unit, and a product name each count as one word.
• Write 6 sentences or fewer in a paragraph.
• Write one instruction in each sentence.
• Use the active voice. Use only the present tense, the past tense and the future tense with "will".
• Do not use semicolons. Write two sentences.
• Do not use contractions.
• Use only these modal verbs: "can", "cannot", "must" and "will". Do not use "should", "may", "would", "might" or "shall".
• Use one word for one meaning. For example, write "use", not "utilize". Write "make sure", not "ensure". Write "approximately", not "about", for a quantity. "About" means "concerned with".
• Do not omit the subject. For example, the TSDoc sentence "Returns the value." is not complete. Write "The function gives the value."
• Do not use "e.g.", "i.e." or "etc.". Write "for example", or rewrite the sentence.
• Write API names, file names, metric names and commands in code format.

The linter

@mark1russell7/ste-lint examines the Markdown and MDX pages and the TSDoc comments. It finds these problems:

• long sentences and long paragraphs
• modal verbs that are not approved
• semicolons and Latin abbreviations
• words with a better alternative
• gender pronouns
• passive instructions
• sentences without a subject

Examine all files:

pnpm lint:ste

Examine some files, with the output in JSON:

pnpm lint:ste "packages/site/content/docs/**/*.mdx" --format json

The configuration is in ste.config.json. It has the glossary of the project: the technical nouns and verbs that the rules permit, for example "heartbeat", "histogram" and "flush". Add a word to the glossary only if it is a real technical term of the project.

The full dictionary of ASD-STE100 is copyrighted. The project does not contain it. You can use a licensed copy:

1. Convert the copy to the format in the README of ste-lint.
2. Keep the file outside the repository.
3. Set STE_DICTIONARY to the path of the file.

Then the linter also reports words that are not in the dictionary.

The same word for the same thing

Add a page

1. Add an .mdx file in packages/site/content/docs, packages/site/content/thesis or packages/site/content/research. The path of the file is the path of the page.
2. Add the frontmatter: title, description and order. For a page that is not complete, add status: draft.
3. Start the text at heading level 2 (##). The page shows the title as the heading of level 1.
4. Use pnpm lint:ste to examine the page, and correct each finding.

The table of contents shows the headings of level 2 and 3.

Frontmatter

Components

Each MDX page can use these components without an import. Put the data for a component in a TypeScript file next to the page, for example browser-support.data.ts. Then import the data in the page.

To add a component, add it to packages/site/src/mdx/component-map.tsx.

Callouts

Facts

Do not write facts about the library that the code or the tests do not show. Write facts about browsers only with a source, for example from the research. Set status: draft on a page with facts that nobody examined.