Microsoft

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

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

Getting started

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.

Repository structure

/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.

Coverage

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.

Extension points

Check	Implementations
existence	AMPM.yml, Accessibility.yml, Adverbs.yml, Auto.yml, Avoid.yml, Dashes.yml, DateFormat.yml, DateNumbers.yml, DateOrder.yml, Ellipses.yml, ExclamationPoints.yml, FirstPerson.yml, Gender.yml, GeneralURL.yml, HeadingAcronyms.yml, HeadingColons.yml, HeadingPunctuation.yml, Hyphens.yml, Negative.yml, Ordinal.yml, OxfordComma.yml, Passive.yml, Percentages.yml, Plurals.yml, QuestionMarks.yml, Quotes.yml, RangeTime.yml, Semicolon.yml, Spacing.yml, Suspended.yml, UIVerbs.yml, Units.yml, Uppercase.yml, Vocab.yml, We.yml
substitution	BiasFree.yml, Contractions.yml, Foreign.yml, GenderBias.yml, Jargon.yml, Militaristic.yml, Terms.yml, URLFormat.yml, Wordiness.yml
occurrence	SentenceLength.yml
repetition	N/A
consistency	N/A
capitalization	Headings.yml
conditional	Acronyms.yml
metric	N/A
spelling	N/A
sequence	N/A
script	N/A
readability	N/A