✍️ Writing

Vale Style Package Builder: Turn a Docs Style Guide into .vale.ini, Vocab Lists, and YAML Rules

Convert a written documentation style guide into a working Vale setup: .vale.ini, accept and reject vocabularies, and substitution, existence, and capitalization rules in YAML, with a rollout plan that starts at warning level.

0.0
0Reviews
P
October 5, 2026

Prompt

Act as a docs-as-code technical writer who maintains Vale configurations for engineering documentation teams. You turn a human style guide into rules Vale can actually enforce, and you tell me which guidance cannot become a rule.

Inputs:
- Style guide excerpt (word choices, banned terms, heading case, product names): [StyleGuide]
- Product and feature names with their exact casing: [ProductNames]
- Repo layout and doc file types (for example docs/**/*.md, README.md): [DocPaths]
- Vale version and any existing packages (Microsoft, Google, write-good, proselint, or none): [ValeSetup]
- CI system that will run Vale (GitHub Actions, GitLab CI, local only): [CI]
- Rollout tolerance (how many existing alerts the team can absorb in week one): [Rollout]
- Output format: [Format]
- Language: [Lang]

Generate:
1. Rule triage table. For every StyleGuide line, classify it as one Vale extension point: substitution (swap map), existence (flag tokens), capitalization (heading scope with $title or $sentence), Vale.Terms via an accept vocabulary, Vale.Avoid via a reject vocabulary, or NOT LINTABLE (tone, audience, judgment calls). Give a one-line reason.
2. .vale.ini. Write StylesPath, MinAlertLevel, Packages taken from ValeSetup, Vocab name, and a glob section built from DocPaths with BasedOnStyles. Turn off any package rule that conflicts with StyleGuide (for example Microsoft.Contractions when the guide bans contractions) using RuleName = NO. If ValeSetup says Vale 3.x, place vocabularies under StylesPath/config/vocabularies/<Name>/; if it says 2.x, use StylesPath/Vocab/<Name>/.
3. Vocabulary files. Write accept.txt from ProductNames (one entry per line, regex allowed only where casing variants are real) and reject.txt from banned terms in StyleGuide.
4. Custom rule YAML files for the house style folder. Each file gets extends, message with %s, level, and either swap, tokens, or match plus scope. Use ignorecase only where the guide is case-insensitive. Keep one concern per file and name files after the guideline.
5. Rollout plan for CI. Start new rules at warning or suggestion, list the command to run (vale sync, then vale against DocPaths), and the step for promoting rules to error once alerts are fixed, sized to Rollout.
6. Not lintable list. Quote each StyleGuide line that stayed manual and suggest the review checklist line that replaces it.

Constraints:
- Valid INI and YAML only; indent YAML with two spaces.
- Do not invent package names or rule names that ValeSetup did not mention, except Vale core rules (Vale.Terms, Vale.Avoid, Vale.Spelling, Vale.Repetition).
- No regex that would match inside code spans; mention TokenIgnores or BlockIgnores if StyleGuide contains code-like terms.
- No em dashes.

Instructions

Replace every [bracket] with your details before running. Works on ChatGPT, Claude, and Gemini.

Generated Output

This image was generated using the prompt above.

Vale Style Package Builder: Turn a Docs Style Guide into .vale.ini, Vocab Lists, and YAML Rules - Result

Examples

Example Input

StyleGuide: Use 'sign in', never 'log in' or 'login' as a verb. Avoid 'simply', 'just', 'easy'. Headings use sentence case. Write 'email' not 'e-mail'. Contractions are fine. Prefer active voice. Address the reader as 'you'.
ProductNames: Fernbank Cloud, Fernbank CLI, FlowGate, kubectl
DocPaths: docs/**/*.md and README.md; code samples in fenced blocks
ValeSetup: Vale 3.x, Microsoft package already synced
CI: GitHub Actions on pull requests
Rollout: about 40 alerts max in week one
Format: triage table, then files
Lang: English

Example Output

1. Rule triage
| StyleGuide line | Vale mechanism | Reason |
| sign in, not log in / login (verb) | substitution | fixed swap pairs |
| avoid simply, just, easy | existence | flag tokens, no replacement |
| headings in sentence case | capitalization, scope heading, $sentence | Vale checks case per heading |
| email not e-mail | substitution | fixed swap |
| contractions are fine | keep Microsoft.Contractions at suggestion | it already nudges toward contractions |
| prefer active voice | Microsoft.Passive at suggestion | heuristic only, keep low |
| address reader as you | NOT LINTABLE | judgment call, reviewer checks |
| product casing | Vale.Terms via accept vocab | enforces exact case |

2. .vale.ini
StylesPath = styles
MinAlertLevel = suggestion
Packages = Microsoft
Vocab = Fernbank

[*.md]
BasedOnStyles = Vale, Microsoft, Fernbank
Microsoft.Contractions = suggestion
Microsoft.Passive = suggestion
Microsoft.Headings = NO

Note: Microsoft.Headings is off so the house Fernbank.Headings rule owns heading case and you do not get double alerts. Markdown code spans and fenced blocks are skipped by default, so kubectl inside backticks is never flagged.

3. styles/config/vocabularies/Fernbank/accept.txt
Fernbank Cloud
Fernbank CLI
FlowGate
kubectl

styles/config/vocabularies/Fernbank/reject.txt
e-mail

4. styles/Fernbank/SignIn.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: warning
ignorecase: true
swap:
  log in: sign in
  log into: sign in to
  login to: sign in to

styles/Fernbank/Email.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: warning
ignorecase: true
swap:
  e-mail: email

styles/Fernbank/Minimizers.yml
extends: existence
message: "Remove '%s'; it can sound dismissive to a stuck reader."
level: suggestion
ignorecase: true
tokens:
  - simply
  - just
  - easy

styles/Fernbank/Headings.yml
extends: capitalization
message: "'%s' should use sentence case."
level: warning
scope: heading
match: $sentence
exceptions:
  - Fernbank Cloud
  - Fernbank CLI
  - FlowGate

Why 'login' as a noun is not swapped: the guide only bans it as a verb, and a swap would also hit 'the login page'. Reviewers catch the verb case until you write a sequence rule.

5. Rollout (GitHub Actions, about 40 alerts)
Week 1: run vale sync, then vale docs README.md locally and count alerts. Everything ships at warning or suggestion, so PRs are annotated but not blocked. Fix the Fernbank.SignIn and Fernbank.Email hits first since they are mechanical.
Week 2: promote SignIn, Email, and Vale.Terms to error. Keep Minimizers and Microsoft.Passive at suggestion.
Week 3: decide whether Headings goes to error after one sprint of clean runs.

6. Not lintable, move to the review checklist
- 'Address the reader as you' becomes: Does every procedure speak to the reader directly?
- 'Prefer active voice' stays a suggestion; reviewer confirms the passive hits that remain are intentional.

Reviews (0)

Please login to leave a review.
Loading reviews...