Open-source project
GitLab documentation style guide
69 rules across 8 topics, naming 331 terms.
- 31 errors
- 28 warnings
- 10 suggestions
- The guide
- docs.gitlab.com
- Rules from
- gitlabhq/gitlabhq
- 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 avoidAbility 4 Alert format 2 Bold emphasis 3 British 120 CI config file Codeblock fences Current status Default branch Dropdown 2 EOL whitespace Element descriptors Future tense 2 Git lab flavored markdown 2 Inclusive language 11 Level 6 List indentation 3 Meaningful link words 3 Multi line links 2 Non standard spaces Offerings 3 Outdated versions Possessive Possessive proper nouns 18 Prerequisites Reading level Repetition Simplicity 6 Spelling Substitution warning 87 Substitutions 60 Table delimiter rows To do 2 Unclear antecedent 10 Wordy 8 Zip Badges-Offerings 3 Badges-Tiers 2 Front matter HTML shortcodes History items 2 History items order Images old Internal link case Internal link extension Internal link format Internal links code Reference links Relative links Short code format Short code syntax Tabs links UI text
Concision
1 rule · long sentences, filler, and wordy phrasesSentence length
Voice and tone
2 rules · person, tense, contractions, and claimsSelf referential Uppercase
Punctuation
8 rules · commas, dashes, quotes, and spacingBad plurals Command strings quoted Non standard hyphens Non standard list dashes Non standard quotes Oxford comma Sentence spacing 3 Word slash word 3
Headings
3 rules · capitalization and punctuation in titlesHeading content 5 Heading depth Heading link
Numbers and dates
1 rule · dates, times, units, and ordinalsUnits 2
Abbreviations
1 rule · acronyms, latin, and periodsLatin terms 3
Source hygiene
1 rule · leftovers that should not shipMerge conflict markers
The word list
Every term this guide’s rules name, and what it says to write instead.
| Instead of | Write | Rule |
|---|---|---|
| a number of | Specify the number or remove the phrase. | |
| ability | Avoid it | |
| ability to | Avoid it | |
| able | Avoid it | |
| able to | Avoid it | |
| active user | billable user | |
| active users | billable users | |
| admin user | administrator | |
| admin users | administrators | |
| administrator permission | administrator access | |
| administrator permissions | administrator access | |
| administrator role | administrator access | |
| aeon | eon | |
| aeroplane | airplane | |
| ageing | aging | |
| agnostic | platform-independent' or 'vendor-neutral | |
| aluminium | aluminum | |
| Amazon's | Avoid it | |
| anaemia | anemia | |
| anaesthesia | anesthesia | |
| analyse | analyze | |
| and so on | Remove 'and so on'. Try to use 'like' and provide examples instead. | |
| and/or | Avoid it | |
| annexe | annex | |
| apologise | apologize | |
| Apple's | Avoid it | |
| as well as | Use 'and' instead of 'as well as'. | |
| at least the Owner role | the Owner role | |
| Atlassian's | Avoid it | |
| authorisation | authorization | |
| authorise | authorize | |
| authorised | authorized | |
| authorising | authorizing | |
| AWS's | Avoid it | |
| Azure's | Avoid it | |
| behaviour | behavior | |
| behaviours | behaviors | |
| bullet | list item | |
| Bundler's | Avoid it | |
| busses | buses | |
| calibre | caliber | |
| can log-in | can log in | |
| can login | can log in | |
| can setup | can set up | |
| can sign-in | can sign in | |
| can signin | can sign in | |
| cancelled | canceled | |
| cancelling | canceling | |
| Capybara's | Avoid it | |
| case insensitive | case-insensitive | |
| case sensitive | case-sensitive | |
| categorise | categorize | |
| categorised | categorized | |
| categorises | categorizes | |
| categorising | categorizing | |
| centre | center | |
| cheque | check | |
| cherry pick | cherry-pick | |
| civilisation | civilization | |
| civilise | civilize |
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