Skip to content

Plain writing and simplification

A reader who has to read a sentence twice has paid for it twice. Simplifying a text removes that cost without removing the facts: the same conditions, the same uncertainty, the same exact labels, in a form the reader understands on the first pass.

This page collects the simplification rules that the house voice, mechanics and global writing guidance rely on. The fontlab-simplify skill applies them.

Choose the level

There are three levels. Pick the one that fits the reader and the surface, then apply it consistently through the piece.

Level Use it for Standard behind it
Plain language Every help page, support reply, release note and explanation. This is the default. ISO 24495-1
Controlled English Procedures, warnings, interface strings, error messages and text that goes to machine translation. ASD-STE100 writing rules, applied without its dictionary
Easy-to-read Dedicated material for readers with reading or learning difficulties, first-run onboarding, short recovery instructions. Inclusion Europe’s Information for all

Each level includes the one above it. Controlled English is plain language with stricter sentence rules. Easy-to-read is controlled English with shorter units, more explanation and a layout built for the reader.

Simplification never overrides a fact. A setting name, a version number, a file format, a key combination or a limitation stays exactly as the source has it.

Plain language: four questions

ISO 24495-1 defines plain language by its result: readers can find what they need, understand it and use it. Ask four questions of every draft.

  1. Relevant. Who is reading, and what are they trying to do? Name the reader before you write: a type designer migrating from Glyphs, a student opening FontLab for the first time, a developer calling the Python API. Leave out what this reader does not need, and include what they cannot do without.
  2. Findable. Can the reader reach the answer from the headings alone? Put the outcome or the main instruction first. Put warnings before the step they concern. Write headings that predict the section, and keep sibling headings in the same grammatical form.
  3. Understandable. Does each sentence say one thing, in words the reader knows, about an actor the reader can identify? Define a term the first time it appears, then use that term every time.
  4. Usable. Can the reader act on it? End with the next step, the place to get help, or the check that confirms success. Where you can, watch a reader try.

Sentence rules

These rules come from ASD-STE100’s structural rules and from the paragraph and sentence rules of The Elements of Style. Apply them strictly in procedures and strings. Apply them as a direction of travel in explanatory prose, where the house voice still wants varied rhythm.

  • One instruction per sentence. “Select the glyph. Choose Glyph > Remove Overlap.” A step that hides a second action in a clause will be half-done.
  • Length. Keep an instruction to about 20 words and a description to about 25. Length alone is not the fault: a long sentence that develops one idea can stay. Split a sentence that carries two ideas.
  • Active voice by default. Name the actor when the actor matters: “FontLab rounds the coordinates.” A passive is right when the actor is unknown or beside the point, and when it keeps the important noun in subject position. Never invent an actor to avoid one.
  • Verbs, not nominalizations. “Check the outlines,” not “perform a check of the outlines.” A noun that hides an action also hides who acts.
  • Single verbs, not phrasal verbs. “Remove,” “start,” “open,” not “take out,” “kick off,” “bring up.” A phrasal verb means something its parts do not, and translation engines often split it.
  • No noun stacks over three words. “Glyph outline node coordinate rounding” is five nouns with no verbs. Write “the option that rounds node coordinates in glyph outlines.”
  • Keep the small words. Do not drop articles, subjects or verbs to save space. “Masters not compatible will be skipped” leaves the reader guessing which masters. “FontLab skips masters that are not compatible.”
  • Positive form. “Keep the window open until export finishes,” not “do not close the window before export finishes.” Keep a negative when the negation is the fact: “The font does not contain a kern feature.”
  • One word, one meaning. If the procedure says select, it does not switch to pick or highlight for the same action. If a page calls it a master, it is not a style or a weight three paragraphs later. See terminology.
  • Simple tenses. Prefer present and simple past. Keep a compound tense when it carries information: “FontLab has saved a backup” says the backup exists now.
  • Lists for sequences. Three or more steps or conditions go in a numbered or bulleted list, with parallel items.

In procedures, interface strings and machine-translation input, split a semicolon-joined sentence into two. In explanatory prose the house punctuation rules apply.

Keep the modality

A hedge is content. “The export may have failed” and “The export failed” are different claims, and only one of them is what the application knows.

When you shorten a sentence, keep every may, can, usually, if and until. Do not promote a possibility to a fact, add a cause the source does not give, or invent a frequency (“the most common cause is…”). If a simpler sentence needs a fact the source lacks, mark the gap with a placeholder instead of supplying one.

When a tense rule and a hedge conflict, the hedge wins: “may have failed” keeps its compound form.

Paragraph rules

  • One topic per paragraph. If the topic needs and to join two unrelated claims, it is two paragraphs.
  • State the topic at or near the start. One transition sentence before it is fine; three sentences of run-up are not.
  • End on the point or its consequence, not on a minor detail or a summary of what the paragraph said.
  • Connect each paragraph to the one before. Three paragraphs in a row opening with In addition or Furthermore are a list in disguise.
  • Vary sentence length. A paragraph of uniformly short sentences reads as a list; a paragraph of uniformly long ones reads as a contract.

Scan before you rewrite

Six habits account for most hard-to-parse prose, especially machine-written prose. Each one can be pointed at in the text.

Habit Example Fix
Synonym rotation “the glyph… the character… the letter” for one object Pick the correct term and keep it.
Hedge stacking “it may potentially help to somewhat improve” State the supported claim once, or delete it.
Nominalization “provides support for variable fonts” “supports variable fonts”
Empty praise seamless, powerful, effortless, cutting-edge Delete it, or show the fact that earns it.
Run-on sentence three ideas joined by semicolons and dashes One idea per sentence.
Soft phrasal verb spin up, dive into, reach out start, read, contact

Do not force a change onto text that already passes. A plain sentence does not need to become a different plain sentence.

What not to simplify

  • Established terms. Type design and font engineering have exact words: contour, node, master, instance, axis, hinting, GPOS. Do not replace them with everyday approximations that lose precision. Define them at first use for a reader who may not know them, and link to the glossary.
  • Interface labels and identifiers. Quote them exactly, even when they are long.
  • Voice. Plain language is not flat language. Keep the house voice’s exact observation and companionable tone. “Short is not the goal” applies here as much as in ISO 24495: the goal is a text the reader understands on the first pass.
  • The reader. Do not write down to an expert. Use you for the reader and keep the register adult, including in easy-to-read text.

Easy-to-read text

Easy-to-read is a separate product, not a stricter edit of the normal page. Write it when the reader needs it, and test it with such readers. The core of the European easy-to-read standards, applied to FontLab material:

  • Find out who will read it and what they need to do. Choose the format: a short page, a video, a single-screen guide.
  • Use words the reader knows. Explain each necessary difficult word, with an everyday example, and repeat the explanation when the word returns.
  • Use the same word for the same thing throughout.
  • Avoid metaphors, idioms and unexplained foreign words.
  • Spell out abbreviations; explain any that must stay, such as OTF or UFO.
  • Prefer words to large numbers and percentages unless the exact number is the instruction.
  • Keep sentences short, address the reader as you, use positive and active sentences.
  • Put information in the order the reader needs it, group one topic in one place, and repeat what matters.
  • Start a new line at a natural phrase break rather than in the middle of a phrase; keep one sentence per line where the layout allows.

The standards also give layout advice: large type, high contrast, no text over images, no full lines in capitals, no italics for emphasis, generous spacing. As a font company we follow the intent and check the claims. The guidelines advise sans serif type throughout. Legibility research does not support a blanket ban on serif typefaces; it supports clear letterforms, adequate size and spacing, and good contrast. Choose a typeface that meets those conditions and test it with readers.

Language editions of the standards differ in their terms and details. The language pages carry the language-specific advice in their Easy-to-read and plain writing or Plain writing sections.

Error messages and code

An error message serves the person who meets it. Name the problem in their words, show a value only when it is safe to show, and say what to do next.

Draft: Invalid input.

Revised: The axis value must be a number between 100 and 900. You entered 1000.

Never put a password, licence key, token or personal detail in an error message. Messages reach logs and screenshots. Describe the shape of the value instead: “The licence key must have 25 characters. The key you entered has 24.”

In code, the same principles apply. Put the main entry point first, give each function one job and a name a domain reader understands, use one name for one concept, and write comments that record why, not what.

Worked example

Draft: It should be noted that in the event that the masters are found to be incompatible, the interpolation process may potentially not be able to be performed successfully, which could result in instances not being generated.

Revised: If the masters are not compatible, FontLab may not be able to interpolate them. In that case, it cannot generate the instances. Make the masters compatible first: each glyph needs the same number of contours and nodes, in the same order, in every master.

The revision keeps the condition (if) and the uncertainty (may). It names the actor, removes the stacked hedges, splits one sentence into three and adds the reader’s next step. That next step is new content, so check it against the product before publishing.

Test with readers

A checklist shows that you looked; a reader shows whether it worked. For an important page, try one of these with a few readers who match the intended audience:

  • Find it. Ask the reader to locate the answer to a specific question and time them.
  • Explain it. Ask the reader to say in their own words what the page tells them to do.
  • Think aloud. Watch the reader use the page for the real task and note where they hesitate.

Revise where readers stumble, not where the draft looked untidy.

Sources