---
title: "Writing"
description: "The system has a voice as deliberately as it has a type scale."
canonical: writing.html
navigation-title: "Writing"
---
# Writing
- [The standard](#the-standard)
- [The terse rule](#the-terse-rule)
- [What the check measures](#what-the-check-measures)
- [The software is the subject](#the-software-is-the-subject)
- [Precision before promotion](#precision-before-promotion)
- [A heading names a subject](#a-heading-names-a-subject)
- [Names stay as written](#names-stay-as-written)
- [Values and inventories](#values-and-inventories)
- [No emoji](#no-emoji)
The system has a voice as deliberately as it has a type scale. A page sounds
like the software that explains what it knows: direct, bounded and short.
Two rules bind every text in this tree. The first is ASD-STE100, Simplified
Technical English. The second is the terse rule: say it once, and cut what the
reader already has. `make verify ARGS=prose` measures what a machine can
measure. Review holds the rest.
## The standard
ASD-STE100 is a controlled language for technical documents. The standard is
free to get from ASD, and its dictionary is the authority for every word this
page does not name. The rules below are the ones this tree holds a text to.
| Rule | Limit |
| --- | --- |
| A sentence in a paragraph | 25 words |
| A sentence in an instruction: a list item, a table cell, a step | 20 words |
| A paragraph | 6 sentences, one topic |
| An instruction | One action, in the imperative. A condition stands before it: "If the gate is red, read the row." |
| Voice | Active. The subject does the work: "The renderer writes the markup." |
| Tense | Simple present. Simple past only for a thing that happened once. |
| Verb forms | No -ing verb forms: "when the gate runs", not \``when running the gate`\`. A noun that ends in -ing is a name and stays. |
| Necessity | `must` for a rule, `can` for an ability, `will` for a future fact. Not `shall`, `should`, `may`, `might`, `could` or `would`. |
| Words | One meaning per word, and the approved word: "make sure", not `ensure`; "before", not `prior to`; "use", not `utilize`. |
| Noun clusters | Three nouns at most in a row. Cut a longer cluster with "of" or a hyphen. |
| Articles | Every noun that takes one gets one. Do not cut "the" to save a word. |
A technical name stays as its source spells it, in mono, and counts as one
word: `sds-code`, `make verify`, `--space-4`.
## The terse rule
The standard limits the sentence. The terse rule limits what the page says.
- Say a rule once, and link to it from everywhere else.
- Cut what the line below already shows.
- Cut the story: what it used to be, who asked, when it broke.
- Cut the second example. One example shows the shape.
- Cut the aside. A sentence that starts with "Note that" is one to delete.
- Keep the reason. A rule without its reason is a preference.
## What the check measures
`scripts/prose.ts` reads every document, every comment in a source file and
every sentence a component or a task prints. It finds:
- a sentence over its limit, and a paragraph over six sentences;
- the passive voice, `is written` and `was given`;
- an -ing verb form after a preposition or an auxiliary, `by running`;
- a modal verb the standard does not approve;
- a word this tree replaced, with the approved word to write instead.
The list of replaced words is `WORDS_REPLACED` in the same file. A word the
dictionary does not approve goes on that list the day review finds it. A noun
that ends in -ing goes on `ING_NOUNS` if it is a name.
## The software is the subject
Make the software, the command or the document the subject: "The renderer
writes the markup before the browser opens it." Then the sentence stays true
outside the page it stands on.
Do not write `we`. It can mean the maintainers, TYPO3, a consumer or the
reader. Write `you` only for an action on the reader's own machine: "Open
the rendered page."
## Precision before promotion
A claim names the boundary that makes it true: the source, the versions, the
prerequisite, the part it leaves out. A limitation stands beside the claim it
limits, not in a footnote.
| Write | Avoid | Why |
| --- | --- | --- |
| "The renderer reads reStructuredText and Markdown." | "We support all common formats." | names the actor and the boundary |
| "The search reads the generated site index." | "Powerful, seamless search." | states the mechanism |
| "No page matched this address." | "Something went wrong." | gives the boundary |
| "Run `make verify` before a commit." | "Run the usual checks." | names an action a reader can repeat |
| "PHP 8.2 or newer; 12.4, 13.4, 14.3 and main." | "The latest versions." | a number a reader can check |
## A heading names a subject
A heading is a noun phrase that names what stands under it, or an instruction
if the section is one: "Install it". It is not a question and not a clause
about `it`. A column of "What it returns", "What it leaves out" differs only
in its last words, and a scan does not reach them.
| Write | Avoid |
| --- | --- |
| "The fallback" | "What the fallback is" |
| "Its limits" | "What it does not do" |
| "Making a specimen" | `How a specimen gets made` |
The question a heading hid belongs in the first sentence under it. A heading
over a table, a list of facts or a log is one word if it can be: **Overview**,
**Commits**, **Access**. A block of data needs no paragraph over it. The reason
for its shape belongs in this documentation.
A manual heading fits on one line of the 210px local contents. Keep it to a
noun phrase or one short clause.
## Names stay as written
Headings use sentence case. A tool name, a package name, a path, a key and a
command keep the spelling of their source, in mono: `@typo3/soul-frontend`,
`data-theme`, `make verify`. Do not title-case, translate or prettify a
machine-named string.
Every text in the tree is English, whatever language the conversation uses.
One vocabulary keeps search terms, examples and reviews on the same thing.
## Values and inventories
A value the design depends on is the rule. Write it exactly: 16px is the icon
floor, 140ms is a transition. "Small" and "quick" hide the constraint.
A count is different. Do not write how many elements, cards, checks or icons
there are. Name the thing and the source that lists it. A count is correct
until the next item lands; the directory stays correct.
## No emoji
An emoji is a platform's drawing with a platform's meaning. Status is a named
icon and text, or the mono check where that glyph is part of machine output.
See [Icons](icons.md) and [Accessibility](accessibility.md).