pantheon-org Plain English Writing
Translates technical content into decision-ready communication for non-technical stakeholders.
When to Use
Apply when writing for: executives, business managers, compliance/legal, or cross-functional stakeholders without the requesting team's domain knowledge.
When Not to Use
Skip when writing for engineers or technical specialists. You may optionally apply selective translation for mixed audiences; consider keeping technical depth for peer reviews or developer-facing docs.
Mindset
Technical writing optimises for completeness. Plain-English writing optimises for decisions.
Before writing a single word, ask:
"What does this person need to decide or do — and what is the minimum information required for that?"
The single most reliable fix: move the recommendation to sentence one. Everything else is secondary.
Decision Framework
┌─────────────────────────────────────────────┐
│ OPENING (required) │
│ Problem + Business impact + Action needed │
├─────────────────────────────────────────────┤
│ SUPPORTING CONTEXT (only if needed) │
│ Background / Options / Tradeoffs / Timeline │
├─────────────────────────────────────────────┤
│ APPENDIX (optional) │
│ Technical detail / Metrics / Implementation │
└─────────────────────────────────────────────┘
If a reader only reads the opening, they must still know what to do.
Workflow
Step 1: Identify Audience
executive (zero jargon) | manager (minimal jargon) | compliance/legal (tech translated) | cross-functional (inline definitions). See references/constraints-and-fallbacks.md for the audience depth guide.
If unknown: Audience: unknown. Applying manager-level clarity (fallback).
Step 2: Define the Outcome
One sentence — what must the reader decide or do? Write it before drafting.
Step 3: Draft Key Message First
Opening must contain: problem + business impact + required action.
BAD: [3 paragraphs of background] "...we recommend approving the budget."
GOOD: "We need your approval for a $50k security fix by Thursday. [Impact follows.]"
Step 4: Add Supporting Context
Every action item MUST follow:
[Owner] must [specific action] by [concrete deadline].
BAD: "The database should be optimized."
GOOD: "Database team (Alex) must optimize query performance by March 15."
For acronym-heavy documents, extract all acronyms first:
grep -oE '\b[A-Z]{2,}\b' file.md | sort -u
Define each, then draft — rewrite still leads with key message, not the glossary.
Step 5: Verify
- [ ] Every acronym defined on first use.
- [ ] Opening paragraph contains the key decision or recommendation.
- [ ] All technical terms translated — no unexplained jargon.
- [ ] Every action: [Owner] must [action] by [deadline].
- [ ] Paragraphs are concise and scannable.
Constraints
Hard rules: ALWAYS state audience · ALWAYS define acronyms · ALWAYS lead with key message for executives · NEVER hide decisions · NEVER use passive voice for owned actions · NEVER leave deadlines undefined · NEVER present options without a recommendation.
Fallback paths (state explicitly at the top of your output before writing):
| Situation | Prefix |
|---|---|
| Unknown audience | Audience: unknown. Applying manager-level clarity (fallback). |
| Unknown terminology | Define inline: "TLS (the encryption protocol that keeps data private)" |
| Conflicting priorities | Multiple critical issues — leading with risk and deadlines. |
Full formats: references/constraints-and-fallbacks.md.
Anti-Patterns
Full catalogue: references/anti-patterns.md.
| # | Anti-pattern | Fix |
|---|---|---|
| AP-1 | Jargon without translation | ALWAYS translate or remove every specialist term |
| AP-2 | Buried key decision | ALWAYS put recommendation in sentence one |
| AP-3 | Passive action language | NEVER use passive voice; use [Owner] must [action] by [deadline] |
| AP-4 | Assumed technical context | NEVER assume prior knowledge; explain from first principles |
| AP-5 | Wall of acronyms | ALWAYS define each acronym on first use |
| AP-6 | Recommendations without deadlines | NEVER leave deadlines undefined; undated = ignored |
| AP-7 | Options without a recommendation | NEVER present options without stating which you recommend |
| AP-8 | Skipping audience identification | ALWAYS start with audience and goal |
References
| File | Purpose |
|---|---|
| references/audience-types.md | Audience format and depth guidance |
| references/jargon-translations.md | Technical-to-plain-language mappings |
| references/anti-patterns.md | Full anti-pattern catalogue with BAD/GOOD examples |
| references/before-after-examples.md | Complete before/after rewrites for 5 document types |
| references/constraints-and-fallbacks.md | Full constraint rules, fallback formats, audience depth guide |
External: PlainLanguage.gov