Prose Linting with Vale

Relevant source files

The following files were used as context for generating this wiki page:

• agent.yml
• content/contribute/style/grammar.md
• content/contribute/style/formatting.md
• content/contribute/style/recommended-words.md
• content/contribute/checklist.md
• CONTRIBUTING.md

Prose linting with Vale is an automated process used in this repository to enforce the Docker documentation style guide. It ensures that all content is clear, consistent, and adheres to established standards for grammar, formatting, and vocabulary. This system is a key part of the quality assurance workflow, helping to maintain a professional and uniform voice across all documentation.

Vale checks are integrated into the Continuous Integration (CI) pipeline. While other validation checks like markdownlint, HTML validation, and link checking can be run locally, Vale's prose linting is executed separately in CI. This is done to avoid excessive output during local development while still guaranteeing that all contributions meet the style guide requirements before being merged.

Sources: agent.yml:21-23, 161-163

Integration into the Documentation Workflow

Vale is a critical component of the automated editing and validation process, particularly within the CI/CD pipeline. The system uses an editor agent to automatically polish and validate content created by a writer agent.

The editor agent's workflow involves:

1. Fixing formatting, style, and syntax issues.
2. Running a local validate script which includes markdownlint, HTML validation, and link checking.
3. Iterating on fixes until the local validation passes.

However, the editor agent's validate tool explicitly does not include Vale to prevent overly verbose local logs. Vale's prose linting is reserved for the final CI checks that run on every pull request. This ensures that fundamental structural and link issues are resolved locally before the more nuanced style and grammar checks are performed.

Sources: agent.yml:102-104, 156-163, CONTRIBUTING.md:46-49

Validation Flow Diagram

The following diagram illustrates the documentation workflow, showing the distinction between local validation and the CI-based Vale linting.

This diagram shows that the editor agent iterates locally until basic validation passes, after which a pull request triggers the full suite of CI checks, including Vale.

Sources: agent.yml:102-104, 156-163

Enforced Style Rules

Vale is configured to enforce the specific rules outlined in the Docker documentation style guide. These rules cover capitalization, vocabulary, grammar, and punctuation.

Capitalization

The style guide mandates sentence case for most elements to ensure consistency and readability. Vale rules are configured to enforce these standards.

Element	Capitalization Rule
Headings & Titles	Sentence case.
UI Elements	Match the capitalization in the user interface. If inconsistent, use sentence case.
Docker Solutions	Title case (e.g., Docker Extensions, Docker Hub).
Job Titles	Capitalized only when immediately preceding a name (e.g., Chief Executive Officer Scott Johnston).
Department Names	Capitalized when referring to the specific department.

Sources: content/contribute/style/grammar.md:32-55, content/contribute/ui.md:18-22

Recommended Word Choices

To maintain a consistent and clear tone, the style guide provides a list of recommended words. Vale is used to detect and flag discouraged terms, suggesting preferred alternatives.

Don't Use	Use Instead	Rationale
click	select	select is more device-agnostic.
easy, easily	(remove)	Subjective and often unnecessary.
e.g.	for example, such as	More explicit and readable.
enable / disable	turn on / turn off	Avoids ableist language.
execute	run	run is a more common and simpler term.
please	(remove)	Unnecessary in technical instructions.
sign in	sign in	Standardized term (avoid log in, logon, etc.).
we	(rephrase to focus on user)	Focus on the user's actions, not on Docker as the creator.

Sources: content/contribute/style/recommended-words.md:7-78, content/contribute/style/voice-tone.md:46-51

Grammar and Punctuation

Vale enforces several key grammatical rules to ensure clarity and consistency.

• Active Voice: Sentences must use active voice to make it clear who is performing the action. The writing checklist suggests checking for passive voice by seeing if "by zombies" can be added after the verb.
• Serial (Oxford) Comma: The Oxford comma is required in lists of three or more items.
• Semicolons: Semicolons are forbidden. Writers should use two separate sentences instead.
• Exclamation Marks: The use of exclamation marks is to be avoided.
• Parentheses: Parentheses are discouraged in technical documentation to improve readability.

Sources: content/contribute/checklist.md:10-17, content/contribute/style/grammar.md:130-154

Formatting

While markdownlint handles many structural formatting rules, the editor agent is also programmed to enforce specific style guide conventions that may be checked by Vale. A primary example is the strict requirement to wrap lines at 80 characters.

Sources: agent.yml:111-112, content/contribute/file-conventions.md:78-79