Plain English Guide
Version 0.1 — Working Draft
How Plain Text Office LLC writes its documentation: user manuals, README files, app pages, store listings, in-app text, error messages, and release notes.
This guide is adapted from A Plain English Handbook, published by the U.S. Securities and Exchange Commission in 1998. The handbook was written for investor disclosures. We kept its core ideas and changed the details to fit software.
Why we write this way
People open our documentation in the middle of a task. They want to get the task done and get back to work. Every extra word, vague sentence, or buried step costs them time. Plain English is not “dumbing down.” It is respect for the reader’s time.
Before you write
Know your reader
Decide who will read the document and what they already know.
| Document | Reader | What they want |
|---|---|---|
| App page, store listing | Someone deciding whether to install | What it does, what it costs, what it runs on |
| User manual | Someone using the app | How to do a task, step by step |
| README | Someone who found the project online | What it is and how to start |
| Error message | Someone who just hit a problem | What went wrong and what to do next |
| Release notes | Someone updating | What changed for them |
Write for the least experienced person who will reasonably read it. Experts skim past plain text easily. Beginners cannot get past jargon.
Know what the software does
Check the app before you describe it. Do not describe planned features, features from memory, or features from another platform. If you cannot confirm something, say it is unknown instead of guessing.
Say what the reader needs first
Put the most important information at the top. Lead each section with the answer, then the details. A reader who stops after one sentence should still leave with the main point.
Words
Use everyday words
| Instead of | Write |
|---|---|
| utilize | use |
| initiate, commence | start |
| terminate | end, close, stop |
| prior to | before |
| in order to | to |
| functionality | feature, or name what it does |
| leverage | use |
| in the event that | if |
| at this point in time | now |
| is able to | can |
Use “you” and “we”
Talk to the reader as “you.” Refer to the company as “we.” Avoid “the user” when you mean the person reading.
- Not: “The user must configure the output folder.”
- But: “Choose an output folder.”
Use strong verbs, not hidden verbs
A hidden verb is a verb turned into a noun, such as “make a selection” or “perform an installation.” Use the verb itself.
| Hidden verb | Strong verb |
|---|---|
| make a selection | select |
| perform an installation | install |
| provide a description of | describe |
| carry out a search | search |
| has the ability to | can |
Cut words that add nothing
Remove “simply,” “just,” “easily,” “basically,” “obviously,” “please note that,” and “it should be noted that.” If a step were easy, the reader would not need the documentation. Telling them it is easy only makes them feel worse when it is not.
Define jargon once, or avoid it
If a technical term is needed, define it the first time it appears. Use the same term every time after that. Do not switch between “folder” and “directory,” or “settings” and “preferences,” in the same document. Use the word the app itself shows.
Avoid Latin abbreviations
Write “for example,” “that is,” and “and so on” instead of “e.g.,” “i.e.,” and “etc.”
Sentences
Keep sentences short
Aim for 20 words or fewer. Give each sentence one idea. If a sentence has “and” or “which” joining two ideas, try splitting it.
Use active voice
Say who does what.
- Not: “The file is saved to the export folder.”
- But: “The app saves the file to the export folder.”
- Not: “The setting can be changed in Preferences.”
- But: “You can change the setting in Preferences.”
Passive voice is fine when the actor does not matter, as in “Your notes are stored as plain text files.”
Use present tense
Describe what the software does, not what it will do.
- Not: “Clicking Export will create a CSV file.”
- But: “Click Export to create a CSV file.”
Say it positively
State what is true or what to do. Avoid double negatives.
- Not: “The app will not run unless the folder is not read-only.”
- But: “The app needs write access to the folder.”
Be concrete
Replace vague words with specifics.
- Not: “Large files may take some time.”
- But: “A 100 MB file takes about 10 seconds to open.”
Use numerals for numbers, sizes, and times: “3 files,” “5 MB,” “2 seconds.”
Instructions
Number the steps
Use a numbered list for any task with more than one step. Put one action in each step.
- Open Settings.
- Select Export.
- Choose a folder, and then select Save.
Put the goal or condition first
Tell the reader why or when before what. They decide whether the step applies before they act.
- Not: “Select Merge if you want to combine the files.”
- But: “To combine the files, select Merge.”
Name things exactly as the app shows them
Copy button, menu, and field names exactly, including capitalization. Put them in bold. Write menu paths with “>”, as in File > Export.
Show the result
After a step that changes something, say what the reader should see. This tells them the step worked.
Show commands and examples exactly
Put commands, file paths, and file contents in code blocks, exactly as the reader would type them. Use real, working examples.
Error messages and in-app text
An error message answers three questions: what happened, why, and what to do next.
- Not: “Error 0x80070005: Operation failed.”
- But: “Can’t save notes.txt because the folder is read-only. Choose another folder or change the folder’s permissions.”
Other rules for in-app text:
- Do not blame the reader. Write “Can’t find that file,” not “You entered an invalid file.”
- Keep button labels to a verb and, if needed, an object: Save, Export CSV, Delete note.
- Ask before anything that cannot be undone, and say what will be lost.
Honesty
- State what is free, what is paid, and what each costs.
- State limits plainly: file size limits, missing platforms, features that are not finished.
- State what data the app collects and where it goes, even when the answer is “nothing, and nowhere.”
- Do not use “seamless,” “powerful,” “blazing fast,” or other claims the reader cannot check.
Layout
- Use headings that say what the section is about. A reader should be able to scan the headings and find their answer.
- Keep paragraphs short: 3 to 5 sentences.
- Use tables to compare options, platforms, or settings.
- Use lists for three or more parallel items.
- Write each fact in one place and link to it elsewhere. The user manual holds the how-to detail; app pages and store listings link to it.
Check your work
Before you publish, read the document as the reader would.
- Can a new reader find the answer to their question in under a minute?
- Does every step match the app as it is today?
- Did you remove words that add nothing?
- Are most sentences under 20 words, in active voice?
- Is every UI label spelled exactly as the app shows it?
- Read it aloud. Rewrite anything you stumble over.
Version history
| Version | Status | Changes |
|---|---|---|
| 0.1 | Working draft | First version |
