The road to v1.0.0

[jdkato]

This is easily the most thorough style I've published to date and, as such, I'd like to use its progress as an opportunity to refine the style development process as a whole.

The rest of the this issue will outline some of my general ideas for reaching v1.0.0 of this style and general improvements to styles overall.

Coverage

We've implemented a good portion of the standalone sections in the guide, but the A-Z word list has been largely untouched. The reasons for this are that it's long (length-wise, it's over half the guide) and many of its suggestions context-dependent.

For example, let's look at the 'fail' entry:

In content for a general audience, use only to refer to disks and other hardware. Use stop responding to refer to programs or the operating system.

It's OK to use fail in content for a technical audience to describe an error condition. For example, E_FAIL is a common return value in COM programs. A function that returns E_FAIL has failed to do something.

The advice above depends on how the word is used -- something that Vale can't reliably detect.

I think the goal for these types of entries should be suggestion-level, existence notifications that provide enough information for the user to determine if they're inline with the guide without having the reference it themselves:

# Fail.yml

extends: existence
link: 'https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/f/fail'
ignorecase: true
level: suggestion
# Ideally this should fit on a single line.
message: "Only use '%s' to refer to disks and other hardware."
# Expanded reasoning can be provided here.
description: |
  Use 'stop' responding to refer to programs or the operating
  system.

  It's OK to use fail in content for a technical audience to describe an error
  condition. For example, E_FAIL is a common return value in COM programs. A
  function that returns E_FAIL has failed to do something.
tokens:
  - 'fail(?:ed)?'

Measuring Coverage

While it's difficult to determine exactly what percentage of a guide has been covered, I propose the following system: Every page in a style guide should have a corresponding YAML document (/coverage/<TOPIC>.yml) that condenses the page down to only what it suggestions:

# /coverage/acronyms.yml

# These are topics on the page that we don't yet cover:
product-or-feature-names: false
audience-is-familiar: false

# The following has an implementation in `Acronyms.yml`.
#
# Acronyms.yml
spell-out-the-term: true

just-once: false

# HeadingAcronyms.yml
titles-and-headings: true

lowercase-the-spelled-out-term: false
a-or-an: false
possessive-form: false

Although somewhat tedious, this would allow us to provide and track an accurate percentage of what we cover.

cc @amyq

[polarweasel]

Is here a good place to mention that Avoid.yml seems to be cut off rather prematurely?

A search like this one for "never use" turns up quite a few (master/slave is what got me looking at Avoid in the first place...). A related search term is "don't use".

Or, a grep over a local copy of the style guide's GitHub repo may be even faster and more useful!

[jdkato]

It's not "cut off"; it's simply not complete yet (as with many other rules here).

[polarweasel]

Accepting PRs for additions, I assume? :)

[jdkato]

Yes, I'd very much appreciate help maintaining this style.

[ShahradR]

Hello!

I started using the Microsoft style in my projects, and I was hoping I could help out a bit on this issue—would it make sense if I created a coverage file for the A-Z word list?

I got started with the "A"s—I put a sample below. If this looks right, I can keep going through the alphabet and start work on a pull request?

Let me know what you think!

# /coverage/AtoZ.yml

abortion: true #Avoid.yml
abort: false
above: true #Vocab.yml
access: true #Vocab.yml
access-key: false
accessible: true #Vocab.yml
achievement: false
actionable: true #Vocab.yml
active-player-active-user: false
adapter: true #Terms.yml
add: false
add-in-add-on: false
adjacent-selection: false
administer: true #Terms.yml
administrator-admin: true #Terms.yml
afterward: true #Terms.yml
against: true #Vocab.yml
ai: false
alarm: true #Vocab.yml
...

[jdkato]

@ShahradR: Yes, this would definitely help us measure our progress.

[ShahradR]

Neat! I'll get started and hopefully should have a pull request ready soon!