Style and glossary

Style and glossary

Two files hold the editorial decisions your team already makes in review. glossary.yaml names the words. style.yaml names the voice.

glossary.yaml

terms:
  - use: project
    not: [space, site]
    because: A project is one documentation property. The app says "project".
  - use: workspace
    not: [org, organisation, tenant]
    because: A workspace holds the people, the billing and the projects.

usestringrequired

The word this documentation uses.

notstring[]required

The words it does not use. Each one becomes a lint warning wherever it appears.

becausestring

Why. It appears in the lint message, so the writer who hit the rule learns the reason instead of only the correction.

A word from a not list on a page raises wrong-term, a warning. It is a warning rather than an error because a quotation may legitimately contain the other word.

style.yaml

voice:
  - Use the active voice.
  - Write short sentences. One instruction to a sentence.
  - Say what the product does today, not what it will do.
avoid:
  - Do not use "simply", "just" or "easy".
  - Do not promise a feature that is not built.

Two lists of short rules. At most 15 of each, and each at most 160 characters.

The limit is deliberate. A rule a person can hold in their head is a rule a model can follow, and a paragraph of guidance is neither.

Where the style guide is used

The lists travel with every request for help with the words. A suggestion comes back sounding like the rest of your pages rather than like a model.

They are the sentences you already say in review. Writing them down once means you stop saying them.

Rules

Rule	Severity	What it means
glossary-invalid	error	The YAML does not match the schema.
style-invalid	warning	The YAML does not match the schema.
wrong-term	warning	A page uses a word the glossary rejects.

The glossary is an error and the style guide is a warning because the glossary is read by the linter on every page, and a broken one would silently stop enforcing your vocabulary.