Plain language principles

Plain language is writing that readers can understand the first time they read it. It is not simplified language — it does not talk down to readers or avoid complexity where complexity is warranted. Plain language is efficient: it delivers information in the clearest, most direct form possible, without unnecessary words, jargon, or structure that makes reading harder than it needs to be.

Plain language matters for all readers and is especially important for readers who are not native English speakers, readers with cognitive disabilities, readers under time pressure, and readers who are new to the subject matter.

How this article fits with the rest of this style guide: plain language isn't a separate rule set — it's the underlying goal that several other articles in this guide already implement in detail. This article is the synthesis piece: it names the principle and points to where each part of it is fully specified, rather than restating each rule from scratch. If you want the complete reasoning behind any individual principle below, follow the cross-reference.

Plain language also happens to be the writing style that search engines and AI systems can extract and cite most reliably — a short, direct, unhedged sentence is exactly the kind of statement a machine can lift out correctly, the same connection made in the What Makes Documentation Good guide's discussion of GEO and AEO.

The Core Principles

Use short, direct sentences

Each sentence should contain one idea. When a sentence contains two or more ideas, each idea competes for attention. Readers who are scanning will miss the second idea. Readers who are translating have more to hold in working memory.

Target sentence length: under 25 words for most sentences in documentation. Conceptual explanations can run longer, but procedural steps should be short.

A concrete self-check: if you have access to a readability tool, a Flesch-Kincaid grade level around 8–10 is a reasonable target for most product documentation — low enough to be broadly accessible, without artificially truncating necessary technical detail. Treat this as a sanity check on a finished draft, not a target to write toward sentence by sentence.

Use everyday words

When a simple word and a complex word mean the same thing, use the simple word. This is not about intelligence — it is about reducing the cognitive load of reading. A reader who does not have to decode your vocabulary can concentrate fully on understanding your content.

Common substitutions:

• utilize → use
• commence → start or begin
• terminate → end or stop
• subsequent → next or following
• prior to → before
• in the event that → if
• demonstrate → show
• facilitate → help or enable

See the Words to Avoid quick reference for a fuller list of specific words and phrases to replace, organized by the problem they cause (condescension, inflation, hedging, filler).

Explain jargon when you must use it

Some jargon is unavoidable in technical documentation — you cannot document an API without using "endpoint" or "request." But jargon that is not explained is a barrier for readers who are not already fluent in it.

Define every technical term the first time it appears in an article. Keep definitions brief and inline: "A webhook — an automatic notification sent to an external system when a specific event occurs — can be configured in Settings."

Use the active voice

Active sentences are shorter, more direct, and easier to understand than passive sentences. They make clear who is doing what. See the Passive Voice as a Default section of the Verbs, Tense, and Mood guide for the full rule and examples; plain language and active voice are natural partners because active voice shortens sentences and removes ambiguity about the actor in exactly the way plain language calls for.

Use lists for multiple items

When a sentence contains three or more items, convert them to a list. Lists are significantly easier to scan and remember than run-on sentences. See the When to Use a List section of the Lists and Tables guide for the full decision criteria on when a list helps and when it fragments information that reads better as prose.

Before: "To complete the setup, you need to configure your notification settings, invite your team members, set up your custom domain, and review your access permissions."

After: "To complete the setup:

• Configure your notification settings
• Invite your team members
• Set up your custom domain
• Review your access permissions"

Put conditions before instructions

When a step or instruction applies only under certain conditions, state the condition before the instruction. This allows readers who are not in that condition to skip ahead without reading the full instruction. See the condition-before-action guidance in the Verbs, Tense, and Mood guide, and its application to procedural steps in the Writing Procedures guide, for the complete rule.

Write for scanning

Most readers do not read documentation linearly. They scan to find the section relevant to them, then read from that point. Structure every article to support this behavior:

• Use descriptive headings so readers can navigate by scanning headings alone — see the Headings and Titles guide for the full rule.
• Put the most important information at the beginning of each section.
• Use bold text to highlight key terms and actions — not for emphasis of random phrases — see the Highlighting section of the Formatting Standards guide.
• Keep paragraphs short: three to five sentences in most cases.

Plain Language Does Not Mean Oversimplified

Plain language does not require removing technical content, avoiding nuance, or treating readers as though they are incapable. It means expressing technical content as clearly and directly as possible. A precisely worded technical statement can be plain language. A vague, hedged, jargon-filled paragraph is not plain language even if no single word is technically complex.

The goal is not short — it is clear. When content genuinely requires length to be accurate and complete, use that length. Plain language means removing unnecessary words, not removing necessary ones.

Self-Audit Checklist

Before publishing, check the article against these questions:

• Does each sentence contain one idea, with most sentences under 25 words?
• Have complex words been replaced with everyday equivalents wherever they mean the same thing?
• Is every technical term defined briefly, inline, on first use?
• Is the writing in active voice, with a clear actor for each action?
• Have run-on sentences with three or more items been converted to lists where appropriate?
• Does every conditional instruction state the condition before the action?
• Can a reader scan the article's headings alone and find the section relevant to them?
• Is content that's genuinely complex still expressed clearly, rather than stripped of necessary nuance to appear simpler?