Repository navigation
Writing for clients
How to write anything a client reads: control panel screens, buttons, messages, help pages and emails. Many clients read English as a second language, so these rules aim for text that is quick to read and has only one possible meaning.
The rules are taken from ASD-STE100, Simplified Technical English, a standard written for aircraft maintenance manuals, where a misunderstood instruction is dangerous. We use its writing rules, not its dictionary: the Glossary does that job for us. This is Rule 11 applied to writing.
| Text | Rules |
|---|---|
| Control panel screens, buttons, messages, emails, client help pages | All the rules below |
| Developer documents (README, wiki, PRD, code comments) | The Glossary and plain English, without the sentence limits |
| Marketing pages (project and course pages) | The Glossary only; they keep their own voice |
1. One instruction per sentence, in the order it is done.
✅ Open your authenticator app. Type the six-digit code. ❌ Type the six-digit code that your authenticator app shows once you have opened it.
2. Short sentences. At most 20 words for an instruction, 25 for an explanation.
3. Active voice. Say who does what.
✅ Type the code. · We could not save the page. ❌ The code should be entered. · The page could not be saved.
4. Start an instruction with the verb.
✅ Choose a password. · Download the codes. ❌ You should now choose a password.
5. One word, one meaning. Use the client word from the Glossary, always the same one. If the panel says Sign in, no other screen says "log in".
6. No idioms, no slang, no jokes in instructions. "Hit Save", "you're all set" and "under the hood" do not translate. Personality belongs on the marketing pages and in the footer, not in an instruction.
7. Say what happened, then what to do. A message names the problem and the next step, in that order.
✅ That code is not right. The codes change every 30 seconds. ✅ This welcome link has expired. Ask whoever set up your account for a new one. ❌ Error 422. · Something went wrong.
8. Numbers as digits, times in full. "15 minutes", "72 hours", "at least 12 characters".
9. Do not rely on colour or position alone. Write "the red message" only if the message also says what is wrong. Write "the box above" only when there is one box above.
10. Lists for steps, not paragraphs. Three steps or more go in a numbered list.
- Can each sentence be read only one way?
- Is every term in the Glossary, with the client word where there is one?
- Would it still make sense if a translation app read it aloud?
- Does every error message say what to do next?
These are already in the panel and follow the rules:
- "Too many attempts. Try again in 15 minutes."
- "That email address and password do not match."
- "Use at least 12 characters. A few words in a row works well."
- "Each code signs you in once. This is the only time they are shown."