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.

DocumentReaderWhat they want
App page, store listingSomeone deciding whether to installWhat it does, what it costs, what it runs on
User manualSomeone using the appHow to do a task, step by step
READMESomeone who found the project onlineWhat it is and how to start
Error messageSomeone who just hit a problemWhat went wrong and what to do next
Release notesSomeone updatingWhat 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 ofWrite
utilizeuse
initiate, commencestart
terminateend, close, stop
prior tobefore
in order toto
functionalityfeature, or name what it does
leverageuse
in the event thatif
at this point in timenow
is able tocan

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 verbStrong verb
make a selectionselect
perform an installationinstall
provide a description ofdescribe
carry out a searchsearch
has the ability tocan

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.

  1. Open Settings.
  2. Select Export.
  3. 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

VersionStatusChanges
0.1Working draftFirst version