Vale CMS Need more than a rule playground? Explore

Open-source project

GitLab documentation style guide

69 rules across 8 topics, naming 331 terms.

  • 31 errors
  • 28 warnings
  • 10 suggestions
Read at
d7b9a61
License
CC-BY-SA-4.0
Used by
3 of 355 public configs

The guide, by topic

Select a rule to see what it asks for.

Word choice

52 rules · preferred terms, jargon, and words to avoid

Concision

1 rule · long sentences, filler, and wordy phrases

Voice and tone

2 rules · person, tense, contractions, and claims

Punctuation

8 rules · commas, dashes, quotes, and spacing

Headings

3 rules · capitalization and punctuation in titles

Numbers and dates

1 rule · dates, times, units, and ordinals

Abbreviations

1 rule · acronyms, latin, and periods

Source hygiene

1 rule · leftovers that should not ship

The word list

Every term this guide’s rules name, and what it says to write instead.

Instead ofWrite
a number ofSpecify the number or remove the phrase.
abilityAvoid it
ability toAvoid it
ableAvoid it
able toAvoid it
active userbillable user
active usersbillable users
admin useradministrator
admin usersadministrators
administrator permissionadministrator access
administrator permissionsadministrator access
administrator roleadministrator access
aeoneon
aeroplaneairplane
ageingaging
agnosticplatform-independent' or 'vendor-neutral
aluminiumaluminum
Amazon'sAvoid it
anaemiaanemia
anaesthesiaanesthesia
analyseanalyze
and so onRemove 'and so on'. Try to use 'like' and provide examples instead.
and/orAvoid it
annexeannex
apologiseapologize
Apple'sAvoid it
as well asUse 'and' instead of 'as well as'.
at least the Owner rolethe Owner role
Atlassian'sAvoid it
authorisationauthorization
authoriseauthorize
authorisedauthorized
authorisingauthorizing
AWS'sAvoid it
Azure'sAvoid it
behaviourbehavior
behavioursbehaviors
bulletlist item
Bundler'sAvoid it
bussesbuses
calibrecaliber
can log-incan log in
can logincan log in
can setupcan set up
can sign-incan sign in
can signincan sign in
cancelledcanceled
cancellingcanceling
Capybara'sAvoid it
case insensitivecase-insensitive
case sensitivecase-sensitive
categorisecategorize
categorisedcategorized
categorisescategorizes
categorisingcategorizing
centrecenter
chequecheck
cherry pickcherry-pick
civilisationcivilization
civilisecivilize

These rules run in Vale, which checks a whole documentation set against a guide in your editor and on every pull request.

All 16 guides