- Read the style guide at style guide for voice, grammar, and content-type conventions.
- Read the plain-language specification at plain language for audience, structure, and testing standards.
- Identify the content type (genre) — term definition, concept note, specification, index page — and follow its conventions from the style guide. Content types are genres in Carolyn Miller’s sense: typified responses to recurring situations, not arbitrary templates [@miller1984].
- Put the main point first. State what the thing is or does before explaining how or why. Structure by reader need, not writer’s reasoning — the shift from writer-based to reader-based prose [@flowerhayes1981].
- Use concrete before abstract: show an example of the concept before giving the formal definition. Learners build understanding from examples to principles [@mayer2009].
- One idea per section. If a section answers two questions, split it. Working memory is limited; each additional concept competes for processing capacity [@sweller1988].
- Put characters in subjects and actions in verbs. “We implemented the system” not “the implementation of the system was carried out” [@williams2006]. Use Lanham’s Paramedic Method for revision: find the action, make it a verb, find the agent, make it the subject [@lanham2006].
- Define technical terms on first use and link to their term definitions if they exist in the vault. Use each term consistently afterward — don’t rotate synonyms for style [@redish2012].
- Don’t tell the reader how to feel about the material. Present it; let them respond [@orwell1946].
- When writing for a non-default audience, include an “Assumed audience” section near the top. Writers systematically overestimate reader comprehension [@schriver1997].
- Mark unsourced factual claims with
[citation needed]. Don’t leave them unmarked.
- After writing, check the document against the plain-language publication checklist. If the content is high-impact (legal, financial, medical, safety), test it with real readers before publishing.