Open-source project
Grafana Writers’ Toolkit
79 rules across 8 topics, naming 318 terms.
- 19 errors
- 42 warnings
- 18 suggestions
- The guide
- grafana.com
- Rules from
- grafana/writers-toolkit
- Read at
- 1e58a17
- License
- Apache-2.0
- Used by
- 1 of 355 public configs
The guide, by topic
Select a rule to see what it asks for.
Word choice
42 rules · preferred terms, jargon, and words to avoidAdmin Admonitions Agentless Allows to Alt text Amazon cloud watch 5 Amazon product names And or Apache project names Archives 3 CHANGELOG 3 Datadog proxy 2 Dialog box 3 Documentation team 2 Drop down End to end Google product names Google slang 5 Google spelling 4 Grafana com Kubernetes 8 Meta monitoring 2 O auth 2 OK 16 Palantir product names Paragraphs Parentheses Please Product possessives 129 Prometheus exporters Quickstart README 3 React Refer to 4 Relref SQL 3 Self managed 2 Shortcodes Simple 4 Spelling Wish Word list 122
Concision
8 rules · long sentences, filler, and wordy phrasesReadability automated readability Readability coleman liau Readability flesch kincaid Readability flesch reading ease Readability gunning fog Readability LIX Readability SMOG Repeated words
Voice and tone
6 rules · person, tense, contractions, and claimsFirst person plural 5 Google contractions 22 Google first person 6 Google passive 177 Google will Timeless 16
Inclusive language
2 rules · gendered, ableist, and loaded termsGoogle gender 3 Google gender bias 35
Punctuation
11 rules · commas, dashes, quotes, and spacingCommand line prompts Exclamation Google ellipses Google em dash Google en dash Google ly hyphens Google optional plurals Google oxford comma Google semicolons Google spacing 2 Smart quotes
Headings
3 rules · capitalization and punctuation in titlesGerunds Google heading punctuation Headings
Numbers and dates
4 rules · dates, times, units, and ordinalsGoogle AMPM 3 Google date format 2 Google ranges Ordinal 9
Abbreviations
3 rules · acronyms, latin, and periodsAcronyms Google periods Latin 2
The word list
Every term this guide’s rules name, and what it says to write instead.
| Instead of | Write | Rule |
|---|---|---|
| 1st | Avoid it | |
| 2nd | Avoid it | |
| 3rd | Avoid it | |
| 4th | Avoid it | |
| 5th | Avoid it | |
| 6th | Avoid it | |
| 7th | Avoid it | |
| 8th | Avoid it | |
| 9th | Avoid it | |
| A-OK | Avoid it | |
| admin | administrator | |
| ADOT's | Avoid it | |
| Agent's | Avoid it | |
| agentless | no-collector | |
| AI Observability's | Avoid it | |
| allows to | allows you to | |
| Alloy's | Avoid it | |
| alumnae | graduates | |
| alumnus | graduate | |
| and/or | Avoid it | |
| Apollo's | Avoid it | |
| are not | aren't | |
| ARN's | Avoid it | |
| as of this writing | Avoid it | |
| Asserts' | Avoid it | |
| at present | Avoid it | |
| Atlassian's | Avoid it | |
| authoress | author | |
| AWS CloudWatch | Amazon CloudWatch | |
| AWS Distro for OpenTelemetry Collector's | Avoid it | |
| AWS X-Ray's | Avoid it | |
| AWS's | Avoid it | |
| Beyla's | Avoid it | |
| blacklist | blocklist | |
| blacklisted | blocklisted | |
| blacklisting | blocklisting | |
| blacklists | blocklists | |
| BoringCrypto's | Avoid it | |
| cadvisor | cAdvisor | |
| cannot | can't | |
| Catchpoint's | Avoid it | |
| CentOS's | Avoid it | |
| centre | Avoid it | |
| ClickHouse's | Avoid it | |
| Cloudwatch | CloudWatch | |
| CloudWatch's | Avoid it | |
| Codespaces' | Avoid it | |
| colour | Avoid it | |
| containerd's | Avoid it | |
| content type | media type | |
| could not | couldn't | |
| CPython's | Avoid it | |
| cron job | CronJob | |
| Crossplane's | Avoid it | |
| currently | Avoid it | |
| Data Firehose's | Avoid it | |
| Databricks' | Avoid it | |
| datacenter | data center | |
| datacenters | data centers | |
| Datadog Proxy | Datadog proxy |
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