clear-writing
Installation
SKILL.md
Clear Writing
ISO 24495-1:2023 defines plain language by its outcome: wording, structure, and design so clear that the intended readers can easily find what they need, understand what they find, and use that information. Everything in this skill serves that outcome.
Two things about the standard shape how you should work:
- It focuses on how well readers can use a document, not on mechanical measures such as readability formulas. So the job is not "shorten sentences and swap hard words." Most of the work is deciding what these readers need and arranging it so they can act on it. Word choice is a small part: the International Plain Language Federation (IPLF) reports that only about 7% of the standard's roughly 485 ideas concern word choice.
- It applies to most written languages, and the IPLF describes it as language-neutral. Apply its guidelines through the conventions of the language you are writing in.
The four principles
The standard treats the principles as interdependent, not as a sequence: a text is usable when its content is relevant, findable, and understandable, and only evaluation shows whether it really is. The steps below follow the principles in working order; go back to an earlier step whenever a later one shows a problem.
| Principle | Reader outcome | Guidelines (clause) |
|---|---|---|
| 1 Relevant | Readers get what they need | 5.1.2 Identify the readers · 5.1.3 Identify the readers' purpose · 5.1.4 Identify the context in which readers will read the document · 5.1.5 Select the document type or types · 5.1.6 Select content that readers need |
| 2 Findable | Readers can easily find what they need | 5.2.2 Structure the document for readers · 5.2.3 Use information design techniques that enable readers to find information · 5.2.4 Use headings to help readers predict what comes next · 5.2.5 Keep supplementary information separate |
| 3 Understandable | Readers can easily understand what they find | 5.3.2 Choose familiar words · 5.3.3 Write clear sentences · 5.3.4 Write concise sentences · 5.3.5 Write clear and concise paragraphs · 5.3.6 Consider including images and multimedia · 5.3.7 Project a respectful tone · 5.3.8 Ensure that the document is cohesive |
| 4 Usable | Readers can easily use the information | 5.4.2 Evaluate the document continually as it is developed · 5.4.3 Evaluate the document further with readers · 5.4.4 Continue to evaluate readers' use of the document |