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
coder · EdwardAngert · Apr 9, 2025 · Apr 9, 2025 · Apr 9, 2025 · Apr 9, 2025
commit aec75e462f0e09bfd62b529c2a811a35d9962053
diff --git a/.github/docs/vale/.vale.ini b/.github/docs/vale/.vale.ini
@@ -1,21 +1,57 @@
 # Vale configuration file for Coder documentation
-# Based on GitLab Vale configuration using Google and GitLab style guides
+# Based on Google and GitLab style guides with additional linters
 
 StylesPath = styles
-MinAlertLevel = suggestion
+MinAlertLevel = warning
 
 # External packages
-Packages = Google, write-good
+Packages = Google, write-good, proselint, alex, readability
 
+# Apply to all Markdown files except excluded paths
 [*.md]
-BasedOnStyles = Google, write-good
+BasedOnStyles = Google, GitLab, write-good, proselint, alex, readability
+
+# Rule-specific configuration
+Google.Passive = warning
+Google.WordList = warning
+Google.Contractions = suggestion
+Google.Acronyms = warning
+
+write-good.E-Prime = NO         # Disable E-Prime check (avoiding "to be" forms)
+write-good.TooWordy = warning
+write-good.Passive = warning
+write-good.Weasel = warning
+
+proselint.Annotations = error   # Ensure TODO, FIXME, etc. are addressed
+proselint.Cliches = warning
+proselint.Typography = warning
+proselint.Hyperbole = suggestion
+
+alex.Ablist = warning           # Catch ableist language
+alex.Gendered = warning         # Catch gendered language
+
+# Exclude auto-generated documentation
+[docs/reference/*.md]
+BasedOnStyles = NO
+
+# Readability configuration
+readability.FleschKincaid = NO    # Don't enforce specific readability score
+readability.GunningFog = NO       # Don't enforce specific readability score 
+
+# Informal style allowances
+write-good.TooWordy = suggestion  # Less strict on informal wording
+proselint.Hyperbole = NO          # Allow more informal/enthusiastic language
 
 # Ignore code blocks and front matter
 BlockIgnores = (?s)```(.|\n)*?```
 BlockIgnores = (?s){{<[^>]*>}}(.|\n)*?{{</[^>]*>}}
+BlockIgnores = (?s)`[^`\n]+`    # Inline code
+BlockIgnores = (?s)^\s*---\n.*?\n---\n  # YAML frontmatter
 
-# Vocabulary exceptions
-TokenIgnores = (\*\*.*?\*\*), (Coder), (OIDC)
+# Vocabulary exceptions - terms that should be allowed
+TokenIgnores = (\*\*.*?\*\*), (Coder), (OIDC), (OAuth), (Kubernetes), (K8s), (EC2), (AWS), (VM), (CLI), 
+  (UI), (API), (IDE), (VS Code), (JetBrains), (dev container), (Terraform), (Docker), (kubectl), 
+  (Helm), (GitHub), (SSH), (Git), (Node.js), (npm), (dev environment), (self-hosted)
 
 # Project-specific word list
 Vale.Terms = YES
diff --git a/.github/docs/vale/styles/Coder/Headings.yml b/.github/docs/vale/styles/Coder/Headings.yml
@@ -0,0 +1,36 @@
+---
+# Heading style checker with exemptions for technical terms
+extends: capitalization
+message: "'%s' should use title case"
+level: warning
+scope: heading
+match: $title
+style: AP # Associated Press style
+exceptions:
+  - Coder
+  - Kubernetes
+  - K8s
+  - AWS
+  - EC2
+  - VM
+  - CLI
+  - API
+  - IDE
+  - UI
+  - VS Code
+  - JetBrains
+  - Docker
+  - Terraform
+  - kubectl
+  - Helm
+  - GitHub
+  - GitLab
+  - OAuth
+  - OIDC
+  - SSH
+  - Git
+  - npm
+  - Node.js
+  - dev container
+  - dev containers
+  - dev environment
diff --git a/.github/docs/vale/styles/Coder/SentenceLength.yml b/.github/docs/vale/styles/Coder/SentenceLength.yml
@@ -0,0 +1,18 @@
+---
+# Checks for sentences that are too long but allows a more conversational style
+extends: metric
+message: "Consider splitting this sentence or simplifying it - it's %s characters long"
+link: https://developers.google.com/style/sentence-structure
+level: suggestion
+scope: sentence
+metrics:
+  - type: character
+    min: 10
+    max: 200  # More generous limit than standard guides
+
+# Exemptions for specific types of content that may have longer sentences
+exceptions:
+  - code blocks
+  - command explanations
+  - configuration examples
+  - URLs
diff --git a/.github/docs/vale/styles/Coder/Terms.yml b/.github/docs/vale/styles/Coder/Terms.yml
@@ -5,11 +5,44 @@ message: "Use '%s' instead of '%s'."
 level: warning
 ignorecase: true
 swap:
-  'VM': 'virtual machine'
-  'K8s': 'Kubernetes'
+  # Capitalization and product names - relaxed for documentation style
+  # Allow both forms of these terms - depends on context  
+  # 'vm': 'virtual machine'
+  # 'VM': 'virtual machine'
+  # Allow K8s as shorthand for Kubernetes
+  # 'k8s': 'Kubernetes'
+  # 'K8s': 'Kubernetes'
   'kubernetes': 'Kubernetes'
-  'AWS EC2': 'Amazon EC2'
+  # Allow both forms - AWS EC2 and Amazon EC2 are both acceptable
+  # 'aws ec2': 'Amazon EC2'
+  # 'AWS EC2': 'Amazon EC2'
+  'terraform': 'Terraform'
+  'docker': 'Docker'
+  'github': 'GitHub'
+  'oauth': 'OAuth'
+  'oidc': 'OIDC'
+
+  # UI and documentation terms
   'CLI tool': 'CLI'
   'web UI': 'dashboard'
   'web ui': 'dashboard'
-  'WebUI': 'dashboard'
+  'WebUI': 'dashboard'
+  'UI interface': 'user interface'
+  'user-interface': 'user interface'
+
+  # Technical terminology - allow informal usage
+  'workspace instance': 'workspace'
+  # Allow 'dev environment' as informal shorthand
+  # 'dev environment': 'development environment'
+  # 'developer environment': 'development environment'
+  'cloud-instance': 'cloud instance'
+  # Allow 'dev container' as it's widely used in docs
+  # 'dev container': 'development container'
+  # 'dev-container': 'development container'
+
+  # Consistency in product features
+  'workspace template': 'template'
+  'remote-development': 'remote development'
+  'self-hosted': 'self-hosted'
+  'on-prem': 'self-hosted'
+  'on-premise': 'self-hosted'
diff --git a/.github/docs/vale/styles/GitLab/Spelling.yml b/.github/docs/vale/styles/GitLab/Spelling.yml
@@ -0,0 +1,37 @@
+---
+# GitLab spelling checks aligned with their style guide
+extends: spelling
+message: "Did you mean '%s'?"
+level: error
+ignore: docs/glossary.md
+swap:
+  # Technology terms 
+  "access(?:ing|ed)? through the UI":  to use the user interface
+  "cli ?commands?": command line commands
+  "command ?line": command-line
+  "e[ -]mail": email
+  "file ?name": filename
+  "java[ -]script": JavaScript
+  "node[ .]js": Node.js
+  "on[ -]premise": on-premises
+  "pre[ -]requisite": prerequisite
+  "style[ -]guide": style guide
+  "type[ -]script": TypeScript
+  "user ?name": username
+
+  # GitLab preferred spellings
+  "admin[ -]level": administrator-level
+  "allowlist": allow list
+  "auto[ -]devops": Auto DevOps
+  "denylist": deny list
+  "dev ?ops": DevOps
+  "down[ -]time": downtime
+  "jira": Jira
+  "k8's": Kubernetes
+  "log[ -]in": login
+  "pgp key": PGP key
+  "run[ -]book": runbook
+  "sign[ -]in": sign in
+  "ssh key": SSH key
+  "two factor": two-factor
+  "web ?hook": webhook
diff --git a/.github/docs/vale/styles/GitLab/SubstitutionWarning.yml b/.github/docs/vale/styles/GitLab/SubstitutionWarning.yml
@@ -0,0 +1,29 @@
+---
+# GitLab style guide substitutions - Warning level
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+ignorecase: true
+swap:
+  'back-end': 'backend'
+  'front-end': 'frontend'
+  'web site': 'website'
+  'web-site': 'website'
+  'click on': 'click'
+  'server side': 'server-side'
+  'client side': 'client-side'
+  'real-time': 'real time'
+  'repo': 'repository'
+  'utilize': 'use'
+  'execution': 'run'
+  'leverage': 'use'
+  'terminate': 'stop'
+  'abort': 'stop'
+  'kill': 'stop'
+  'implement': 'create'
+  'desire': 'want'
+  'robust': 'reliable'
+  'dropdown': 'drop-down'
+  'popup': 'pop-up'
+  'in order to': 'to'
+  'lets': 'let''s'