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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy