Public sector
Vale for the public sector
Plain English for the public, held to a government style guide.
Writing for the public has rules a product team’s docs don’t: plain English anyone can follow, words a government style guide tells you to avoid, acronyms defined the first time, and content that works with a screen reader. GOV.UK publishes its technical style guide as a Vale package any team can install, and the Readability, A11y, and alex packages check reading level, accessibility, and inclusive language on top.
Start with this config
The GOV.UK style installs by its release URL. Readability scores the reading level, A11y checks alt text, link text, and headings, and alex flags insensitive language. On a short page the readability scores fire as suggestions; raise MinAlertLevel to warning to see only the rest.
.vale.ini
StylesPath = styles
MinAlertLevel = suggestion
Packages = https://github.com/alphagov/tech-docs-linter/releases/latest/download/tech-writing-style-guide.zip, \
Readability, A11y, alex
[content/*.md]
BasedOnStyles = Vale, tech-writing-style-guide, Readability, A11y, alex Then download the packages it names and run Vale over the project:
$ vale sync
$ vale . Packages
Published styles to start from. A package in the Explorer installs by name with Packages and vale sync, one published elsewhere by its release URL, and every rule in either can be turned off or changed in your own config.
GOV.UK
The GOV.UK Technical Style guide as Vale rules: words to avoid, words to avoid unless a condition holds, acronyms defined on first use, and common misspellings. Published by the Government Digital Service.
Readability
Readability scores: Automated Readability Index, Coleman-Liau, Flesch-Kincaid, Flesch reading ease, Gunning fog, LIX, and SMOG, with a rule that names the polysyllables behind them.
8 rules 288K downloads
A11y
Accessible writing: alt text, link text, heading structure, table headers, instructions that rely on color or position, a reading grade per paragraph, and an inclusive-language word list, from the parts of WCAG 2.2 that live in the text.
19 rules 12.7K downloads
alex
Catch insensitive, inconsiderate writing.
18 rules 445.8K downloads
neighbor
Accessibility and inclusive language rules for Vale. Flags exclusionary language, ableist terms, metaphors, and complex idioms.
13 rules 17.5K downloads
write-good
Naive linter for English prose for developers who can't write good.
9 rules 1.5M downloads
Where it runs
Content designers often write in a browser, not a code editor, so the extension checks text where it’s typed. The same rules then run in CI before anything is published.
- Browser Chrome, Edge, Firefox
- VS Code VS Code, Cursor, Windsurf
- GitHub Actions vale-cli/vale-action
- pre-commit Local hooks
- Mintlify Built-in CI check
With an agent
All agent toolsThe agent tools install as a Claude Code plugin: skills for setting up and tuning Vale, and hooks that lint each file the assistant writes. Type both lines in Claude Code, then ask for what you need.
/plugin marketplace add vale-cli/agent-tools
/plugin install vale@agent-tools - “set up vale end to end” /vale:onboard Try the style packages against your docs in a temp directory, draft a vocabulary, a decision per noisy rule, and the CI job, and show one proposal with before and after counts.
- “enforce our style guide” /vale:from-guide Turn a written style guide into the project’s own rules, each linked to its section and tested against the guide’s own do and don’t examples.
- “use title case headings” /vale:tune Change one style choice in plain words: headings, contractions, “we”, passive voice, preferred terms. Ships tested templates for the choices no package covers.
- “stop flagging our product name” /vale:vocab Add project terms to a vocabulary, import a word list kept for another spell checker, and set up a regional or other-language dictionary.
Who runs it
Governments, agencies, and public-interest groups running Vale on what they publish: service guidance, architecture decisions, specifications, and the docs for public platforms.
- GOV.UK Publishes the GOV.UK Technical Style guide as a public Vale style package.
- GOV.UK One Login Fails on errors from the GOV.UK tech-writing style across its repos.
- Defra Checks its architecture guidance in Markdown against its own Defra style and vocabulary, reported as warnings on pull requests.
- DigitalService Lints documentation and TypeScript comments in a German federal justice service with the proselint and alex packages and a project vocabulary.
- Government of Western Australia Lints its architecture decision records in Markdown and Quarto with the Microsoft and write-good packages.
- NASA Runs NASA and plain-language styles over the Terra UI components, which GES DISC builds on too.
- Platform One Offers Vale as a prose-linting stage in its Padawan pipelines, with Vale's built-in style and write-good.
- ICTU Lints the docs for its SonarQube image with proselint.
- OASIS Open Lints the prose of the CSAF and SARIF specifications with Vale's built-in style.
- HURIDOCS Enforces an Uwazi style at the error level across the Uwazi knowledge hub.
Formats
Where this kind of writing lives. Vale parses each one, so rules see the prose and skip the markup, the code, and the URLs.
Read more
In the docs
- Readability
Reading-level checks
- Substitution
Turning a words-to-avoid list into a rule
- Packages
Installing a style by its URL
- Vocabularies
Other kinds of writing
Technical
Docs, references, and the style guide your team already follows.
Read the guideResearch
Papers, notebooks, and the docs for the software research runs on.
Read the guideCreative
Fiction, essays, and the rules writers have argued over for a century.
Read the guideCode & data
The prose inside files that aren’t prose: comments, API descriptions, and the log.
Read the guideAI & agents
Hold what a model writes, and what you write for one, to a standard.
Read the guide