Open-source project
Canonical documentation style guide
26 rules across 4 topics, naming 72 terms.
- 5 errors
- 10 warnings
- 11 suggestions
- Rules from
- canonical/documentation-style-guide
- Read at
- 705da79
- License
- CC-BY-SA-4.0
The guide, by topic
Select a rule to see what it asks for.
Word choice
21 rules · preferred terms, jargon, and words to avoid000-US-spellcheck 003-Ubuntu-names-versions 53 004-Canonical-product-names 22 005-Industry-product-names 12 010-Punctuation-double-spaces 012-date-format 7 013-Spell-out-numbers-below-10 10 014a-Numbers-greater-than-nine-should-be-in-numeric-form 23 014b-Numbers-with-five-or-more-digits-must-have-comma-separators 015-No-prompts-in-comments 016-No-inline-comments 4 017a-Suggest-code-over-25-lines 4 017b-Warn-code-over-35-lines 4 019-no-external-images 6 025a-latinisms-with-english-equivalents 23 025b-latinisms-to-reconsider 025c-latinisms-to-avoid 6 026-hints-tips 4 027-non-descriptive-link-text 4 028-flag-todo-comments 3 400-Enforce-inclusive-terms 18
Concision
1 rule · long sentences, filler, and wordy phrases500-Repeated-words
Voice and tone
1 rule · person, tense, contractions, and claims006-Contractions-forbidden 12
Headings
3 rules · capitalization and punctuation in titles007-Headings-sentence-case 008-Headings-no-punctuation 009-Headings-no-links 12
The word list
Every term this guide’s rules name, and what it says to write instead.
| Instead of | Write | Rule |
|---|---|---|
| Anbox | Anbox | |
| Aws | AWS | |
| billion | Avoid it | |
| Canononical Observability Stack | Canonical Observability Stack | |
| chairman | Avoid it | |
| Charmed | Charmed | |
| circa | 'around' or 'near' | |
| Cloud | Cloud | |
| docker | Docker | |
| eighteen | Avoid it | |
| eighty | Avoid it | |
| eleven | Avoid it | |
| ergo | 'therefore' or 'hence' | |
| fifteen | Avoid it | |
| fifty | Avoid it | |
| foreman | Avoid it | |
| forty | Avoid it | |
| fourteen | Avoid it | |
| gonna | going to | |
| Google cloud | Google Cloud Platform | |
| Google cloud platform | Google Cloud Platform | |
| gotta | got to | |
| gratis | 'free' | |
| hundred | Avoid it | |
| Influxdb | InfluxDB | |
| Juju | Juju | |
| Kubeflow | Kubeflow | |
| KubeFlow | Kubeflow | |
| Kuberentes | Kubernetes | |
| Launchpad | Launchpad | |
| LXD | LXD | |
| MAAS | MAAS | |
| manned | Avoid it | |
| mattermost | Mattermost | |
| MicroCeph | MicroCeph | |
| MicroCloud | MicroCloud | |
| MicroK8s | MicroK8s | |
| MicroOVN | MicroOVN | |
| MicroStack | MicroStack | |
| middleman | Avoid it | |
| million | Avoid it | |
| Multipass | Multipass | |
| Mysql | MySQL | |
| nineteen | Avoid it | |
| ninety | Avoid it | |
| nVidia | NVIDIA | |
| Observability Stack | Observability Stack | |
| Openstack | OpenStack | |
| Postgresql | PostgreSQL | |
| Pro | Pro | |
| proviso | 'condition' or 'provided that' | |
| sanity check | Avoid it | |
| seventeen | Avoid it | |
| seventy | Avoid it | |
| sic | Avoid it | |
| sixteen | Avoid it | |
| sixty | Avoid it | |
| Snapcraft | Snapcraft | |
| snapd | snapd | |
| stanza | 'division', 'block', or 'paragraph' |
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