NOTE: This project is neither maintained nor endorsed by Microsoft.

This repository contains a Vale-compatible implementation of the Microsoft Writing Style Guide (LICENSE).

To get started, add the package to your configuration file (as shown below) and then run vale sync.

StylesPath = styles
MinAlertLevel = suggestion

Packages = Microsoft

[*]
BasedOnStyles = Vale, Microsoft

See Packages for more information.

/Microsoft

The YAML-based rule implementations that make up our style.

/fixtures

The individual unit tests. Each directory should be named after a rule found in /Microsoft and include its own .vale.ini file that isolates its target rule.

/testdata

The expected Vale output for each fixture directory, one <Rule>.ct file per fixture. We use go-cmdtest to run Vale against each fixture and compare its output. Run the suite with go test ./...; regenerate the expectations after an intentional change with go test ./... -update.

/coverage

How much of the style guide we implement, tracked topic by topic. Each file mirrors one top-level section of the guide, and each key is a subtopic set to true or false, optionally followed by a comment naming the rules that implement it.

Run go test -v -run TestCoverage ./... to print the current figures:

  guidelines:     37/64 (57.8%)
  A-Z word list:  106/849 (12.5%)

The two are reported separately because the A–Z word list is roughly ten times the size of everything else, so a single combined percentage tells you almost nothing about the guidelines.

The same test enforces what keeps the number honest: values must be exactly true or false, and every rule named in a comment must still exist. A rule that's renamed or merged away therefore can't leave a topic silently claiming coverage it no longer has.

Sections of the guide that describe process rather than prose have no manifest, since there's nothing there for a linter to check: Checklists, Content planning, Design planning, Final publishing review, Search and writing, and Top 10 tips. Scannable content and Text formatting are also absent for now; their lintable subtopics (headings, sentence-style capitalization) are already counted under capitalization.yml, and listing them again would double-count.