p0149.md 7.4 KB
Change documentation style guide
Table of contents
Problem
There's disagreement with the current Google developer documentation style guide. We should make sure the core team has a consensus on the style guide chosen.
Background
The status quo is that we use the Google style guide, per CONTRIBUTING.md. There's basic support for a style guide in order to avoid protracted debate about formatting and to maintain basic consistency.
Key desires for a style guide are:
- Actively maintained.
- Freely available for contributors.
Common deviations
CONTRIBUTING.md notes a couple deviations from the Google style guide. These may be assumed to apply regardless of the style guide, as the relevant styles are common to Microsoft's style guide.
Proposal
A style guide should be chosen. The only candidates found are:
- Google developer documentation style guide
- Microsoft writing style guide
This may be done with or without additional modifications, such as the em-dash exception in CONTRIBUTING.md.
Open question: Which style guide?
Decision: Google style guide
Details
A few key items are highlighted from both style guides for comparison.
Google developer documentation style guide
https://developers.google.com/style
- Dates and times: January 19, 2017 or 2017-04-15 3:45 PM.
- Lists: nuanced guidance for punctuation.
- Non-English words: mostly covered through the word list and abbreviations.
- Punctuation:
- Commas: Oxford.
- Parentheses: use judiciously.
- Semicolons: use judiciously.
- Word list:
- Letter links, such as i.
- Easy to skim comments on words.
Microsoft writing style guide
https://docs.microsoft.com/en-us/style-guide/welcome/
- Dates and times: February 16, 2016, 3:45 PM. Only use digits for dates in locale-customzied UIs.
- Lists: use a period if any item is a complete sentence.
- Non-English words: avoid.
- Punctuation:
- Commas: Oxford.
- Parentheses: no guidance, sentence-length parenthetical examples.
- Semicolons: avoid.
- Word list:
- Letter links and individual word links, such as illegal.
- No way to skim comments on words; each needs to be read individually.
Word lists
NOTE: Due to the noted lack of support for skimming Microsoft's word list, it may be that Microsoft has other noteworthy guidance for terms that Google doesn't.
above
: Google: Use preceding.
: Microsoft: "Use previous, preceding, or earlier."
and so on
: Google: See etc.
: Microsoft: "Use such as or like."
below
: Google: Use following.
: Microsoft: "Use a link, or use later or the following."
blacklist
: Google: Use blocklist.
: Microsoft: "Use block list instead. Note that block list is two words."
cons
: Google: Use disadvantages.
: Microsoft: No guidance.
CLI
: Google: Use command-line tool.
: Microsoft: No guidance.
client
: Google: Short for "client app", say "library" for "client library".
: Microsoft: Use customer to refer to people.
e.g.
: Google: Use for example or such as. Too many people mix up e.g. and i.e.
: Microsoft: "Use for example, such as, or like, as appropriate."
etc.
: Google: Avoid if possible, but use instead of and so on.
: Microsoft: "Use such as or like followed by an example or two."
filename, file name
: Google: one word.
: Microsoft: two words.
file name extension, extension
: Google: No guidance, but "filename extension" is used in the guide.
: Microsoft: Use instead of file extension.
flag
: Google: Use option.
: Microsoft: No guidance.
for instance
: Google: Use for example or such as.
: Microsoft: No guidance.
i.e.
: Google: Use that is.
: Microsoft: Use that is.
illegal
: Google: No guidance.
: Microsoft: "Don't use to mean invalid or not valid."
just
: Google: Don't use.
: Microsoft: No guidance.
master/slave
: Google: Use master with caution. Don't use slave. Multiple alternatives given.
: Microsoft: Don't use master/slave. Multiple alternatives given.
native
: Google: Avoid and use more precise terms when possible, such as "built-in".
: Microsoft: Only guidance is for native language. "Don't use to refer to a computer system's machine language. Use machine language or host language instead."
pros
: Google: Use advantages.
: Microsoft: No guidance.
quick
: Google: Avoid.
: Microsoft: No guidance.
regex
: Google: Use regular expression.
: Microsoft: No guidance.
repo
: Google: Use repository.
: Microsoft: No guidance.
should
: Google: Avoid because it's ambiguous.
: Microsoft: "Before using should or must, consider other ways to discuss recommendations or requirements."
simple, simply
: Google: Avoid; "what might be simple for you might not be simple for others."
: Microsoft: Only guidance is for simply; nothing for simple. "Don't use to mean that something is easy to do."
tl;dr
: Google: Use to summarize.
: Microsoft: No guidance.
traditional
: Google: Avoid.
: Microsoft: No guidance.
via
: Google: Don't use.
: Microsoft: No explicit guidance, but might be considered to fall under non-English words.
vice versa
: Google: Use other way around or conversely.
: Microsoft: No explicit guidance, but might be considered to fall under non-English words.
vs.
: Google: Use versus.
: Microsoft: Use versus.
Alternatives considered
Various offline resources like the Chicago Manual of Style may be helpful to some, but require a subscription or physical copy, and so are less useful as canonical resources for contributors.