The road to v1.0.0 #15
Description
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: falseAlthough somewhat tedious, this would allow us to provide and track an accurate percentage of what we cover.
cc @amyq