Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit aec75e4

Browse files
EdwardAngertEdwardAngert
committed
feat(docs): customize Vale style checking for informal documentation style
- Add readability checks with appropriate thresholds - Allow informal terms like 'K8s', 'dev container', 'AWS EC2' common in docs - Add technical terminology exceptions to heading case rules - Balance formal style with pragmatic documentation practices
1 parent 0301e90 commit aec75e4

File tree

6 files changed

+199
-10
lines changed

6 files changed

+199
-10
lines changed

‎.github/docs/vale/.vale.ini

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,57 @@
11
# Vale configuration file for Coder documentation
2-
# Based on GitLab Vale configuration using Google and GitLab style guides
2+
# Based on Google and GitLab style guides with additional linters
33

44
StylesPath = styles
5-
MinAlertLevel = suggestion
5+
MinAlertLevel = warning
66

77
# External packages
8-
Packages = Google, write-good
8+
Packages = Google, write-good, proselint, alex, readability
99

10+
# Apply to all Markdown files except excluded paths
1011
[*.md]
11-
BasedOnStyles = Google, write-good
12+
BasedOnStyles = Google, GitLab, write-good, proselint, alex, readability
13+
14+
# Rule-specific configuration
15+
Google.Passive = warning
16+
Google.WordList = warning
17+
Google.Contractions = suggestion
18+
Google.Acronyms = warning
19+
20+
write-good.E-Prime = NO # Disable E-Prime check (avoiding "to be" forms)
21+
write-good.TooWordy = warning
22+
write-good.Passive = warning
23+
write-good.Weasel = warning
24+
25+
proselint.Annotations = error # Ensure TODO, FIXME, etc. are addressed
26+
proselint.Cliches = warning
27+
proselint.Typography = warning
28+
proselint.Hyperbole = suggestion
29+
30+
alex.Ablist = warning # Catch ableist language
31+
alex.Gendered = warning # Catch gendered language
32+
33+
# Exclude auto-generated documentation
34+
[docs/reference/*.md]
35+
BasedOnStyles = NO
36+
37+
# Readability configuration
38+
readability.FleschKincaid = NO # Don't enforce specific readability score
39+
readability.GunningFog = NO # Don't enforce specific readability score
40+
41+
# Informal style allowances
42+
write-good.TooWordy = suggestion # Less strict on informal wording
43+
proselint.Hyperbole = NO # Allow more informal/enthusiastic language
1244

1345
# Ignore code blocks and front matter
1446
BlockIgnores = (?s)```(.|\n)*?```
1547
BlockIgnores = (?s){{<[^>]*>}}(.|\n)*?{{</[^>]*>}}
48+
BlockIgnores = (?s)`[^`\n]+` # Inline code
49+
BlockIgnores = (?s)^\s*---\n.*?\n---\n # YAML frontmatter
1650

17-
# Vocabulary exceptions
18-
TokenIgnores = (\*\*.*?\*\*), (Coder), (OIDC)
51+
# Vocabulary exceptions - terms that should be allowed
52+
TokenIgnores = (\*\*.*?\*\*), (Coder), (OIDC), (OAuth), (Kubernetes), (K8s), (EC2), (AWS), (VM), (CLI),
53+
(UI), (API), (IDE), (VS Code), (JetBrains), (dev container), (Terraform), (Docker), (kubectl),
54+
(Helm), (GitHub), (SSH), (Git), (Node.js), (npm), (dev environment), (self-hosted)
1955

2056
# Project-specific word list
2157
Vale.Terms = YES

‎.github/docs/vale/styles/Coder/Headings.yml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
# Heading style checker with exemptions for technical terms
3+
extends: capitalization
4+
message: "'%s' should use title case"
5+
level: warning
6+
scope: heading
7+
match: $title
8+
style: AP # Associated Press style
9+
exceptions:
10+
- Coder
11+
- Kubernetes
12+
- K8s
13+
- AWS
14+
- EC2
15+
- VM
16+
- CLI
17+
- API
18+
- IDE
19+
- UI
20+
- VS Code
21+
- JetBrains
22+
- Docker
23+
- Terraform
24+
- kubectl
25+
- Helm
26+
- GitHub
27+
- GitLab
28+
- OAuth
29+
- OIDC
30+
- SSH
31+
- Git
32+
- npm
33+
- Node.js
34+
- dev container
35+
- dev containers
36+
- dev environment

‎.github/docs/vale/styles/Coder/SentenceLength.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
# Checks for sentences that are too long but allows a more conversational style
3+
extends: metric
4+
message: "Consider splitting this sentence or simplifying it - it's %s characters long"
5+
link: https://developers.google.com/style/sentence-structure
6+
level: suggestion
7+
scope: sentence
8+
metrics:
9+
- type: character
10+
min: 10
11+
max: 200 # More generous limit than standard guides
12+
13+
# Exemptions for specific types of content that may have longer sentences
14+
exceptions:
15+
- code blocks
16+
- command explanations
17+
- configuration examples
18+
- URLs

‎.github/docs/vale/styles/Coder/Terms.yml

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,44 @@ message: "Use '%s' instead of '%s'."
55
level: warning
66
ignorecase: true
77
swap:
8-
'VM': 'virtual machine'
9-
'K8s': 'Kubernetes'
8+
# Capitalization and product names - relaxed for documentation style
9+
# Allow both forms of these terms - depends on context
10+
# 'vm': 'virtual machine'
11+
# 'VM': 'virtual machine'
12+
# Allow K8s as shorthand for Kubernetes
13+
# 'k8s': 'Kubernetes'
14+
# 'K8s': 'Kubernetes'
1015
'kubernetes': 'Kubernetes'
11-
'AWS EC2': 'Amazon EC2'
16+
# Allow both forms - AWS EC2 and Amazon EC2 are both acceptable
17+
# 'aws ec2': 'Amazon EC2'
18+
# 'AWS EC2': 'Amazon EC2'
19+
'terraform': 'Terraform'
20+
'docker': 'Docker'
21+
'github': 'GitHub'
22+
'oauth': 'OAuth'
23+
'oidc': 'OIDC'
24+
25+
# UI and documentation terms
1226
'CLI tool': 'CLI'
1327
'web UI': 'dashboard'
1428
'web ui': 'dashboard'
15-
'WebUI': 'dashboard'
29+
'WebUI': 'dashboard'
30+
'UI interface': 'user interface'
31+
'user-interface': 'user interface'
32+
33+
# Technical terminology - allow informal usage
34+
'workspace instance': 'workspace'
35+
# Allow 'dev environment' as informal shorthand
36+
# 'dev environment': 'development environment'
37+
# 'developer environment': 'development environment'
38+
'cloud-instance': 'cloud instance'
39+
# Allow 'dev container' as it's widely used in docs
40+
# 'dev container': 'development container'
41+
# 'dev-container': 'development container'
42+
43+
# Consistency in product features
44+
'workspace template': 'template'
45+
'remote-development': 'remote development'
46+
'self-hosted': 'self-hosted'
47+
'on-prem': 'self-hosted'
48+
'on-premise': 'self-hosted'

‎.github/docs/vale/styles/GitLab/Spelling.yml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
# GitLab spelling checks aligned with their style guide
3+
extends: spelling
4+
message: "Did you mean '%s'?"
5+
level: error
6+
ignore: docs/glossary.md
7+
swap:
8+
# Technology terms
9+
"access(?:ing|ed)? through the UI": to use the user interface
10+
"cli ?commands?": command line commands
11+
"command ?line": command-line
12+
"e[ -]mail": email
13+
"file ?name": filename
14+
"java[ -]script": JavaScript
15+
"node[ .]js": Node.js
16+
"on[ -]premise": on-premises
17+
"pre[ -]requisite": prerequisite
18+
"style[ -]guide": style guide
19+
"type[ -]script": TypeScript
20+
"user ?name": username
21+
22+
# GitLab preferred spellings
23+
"admin[ -]level": administrator-level
24+
"allowlist": allow list
25+
"auto[ -]devops": Auto DevOps
26+
"denylist": deny list
27+
"dev ?ops": DevOps
28+
"down[ -]time": downtime
29+
"jira": Jira
30+
"k8's": Kubernetes
31+
"log[ -]in": login
32+
"pgp key": PGP key
33+
"run[ -]book": runbook
34+
"sign[ -]in": sign in
35+
"ssh key": SSH key
36+
"two factor": two-factor
37+
"web ?hook": webhook

‎.github/docs/vale/styles/GitLab/SubstitutionWarning.yml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
# GitLab style guide substitutions - Warning level
3+
extends: substitution
4+
message: "Use '%s' instead of '%s'."
5+
level: warning
6+
ignorecase: true
7+
swap:
8+
'back-end': 'backend'
9+
'front-end': 'frontend'
10+
'web site': 'website'
11+
'web-site': 'website'
12+
'click on': 'click'
13+
'server side': 'server-side'
14+
'client side': 'client-side'
15+
'real-time': 'real time'
16+
'repo': 'repository'
17+
'utilize': 'use'
18+
'execution': 'run'
19+
'leverage': 'use'
20+
'terminate': 'stop'
21+
'abort': 'stop'
22+
'kill': 'stop'
23+
'implement': 'create'
24+
'desire': 'want'
25+
'robust': 'reliable'
26+
'dropdown': 'drop-down'
27+
'popup': 'pop-up'
28+
'in order to': 'to'
29+
'lets': 'let''s'

0 commit comments

Comments
 (0)