Avoid acronyms

[camerons]

Doc: https://github.com/thegooddocsproject/templates/blob/master/writing-tips.md

Re:

Avoid colloquialisms and jargon because it makes it harder for a non-native English speaker to understand your words.

Hannah McKenzie 13:36 14 Nov Perhaps worth mentioning to avoid acronyms too?

[naomis-github]

Should we also add that spelling should be consistent throughout the doc (e.g. words with hyphens should always be hyphenated every time it is used)?

[camerons]

Yes @naomis-github, that is a good suggestion. We have decided to align ourselves with the the Google developer documentation style guide, https://developers.google.com/style . Also, I'm aware that a number of our writers (myself included) sometimes use the free version of https://www.grammarly.com/. One thing that would be valuable would be to determine whether grammarly aligns with the Google Style Guide. And then to do an audit against the style guide and fix issues that you find.

[jaredmorgs]

I'm trying to find citations about what style guides Grammarly adopts but they appear to be pretty tight-lipped about it.

errara-ai offer a linter called Vale that lets you select from various style guides like Google, Microsoft but it is non trivial to set up.

[jaredmorgs]

https://developers.google.com/style/abbreviations has how to deal with that covered

[naomis-github]

I just had a look at grammarly; indeed, it doesn't look like they have an openly available writing guideline. They offer writing style settings (i.e. academic, business, technical, casual, creative) if that helps.

[camerons]

An editor of one of my articles has recently pointed me to https://languagetool.org/ which is an open source equivalent to grammarly, sponsored by the European Union, which we could either decide to use as is, or configure to work with the style guide we choose (currently the Google Developers Style Guide).

[bjnath]

Given the nascent state of automated Natural Language Understanding, I hesitate to put any program in a position of final authority. We can take its counsel, just as we take it from colleagues, but the ultimate decision belongs in human hands.

I'll go further and say it belongs in a single pair of human hands. We decide whose hands and record every decision for consistency going forward.

[bjnath]

To be clear, I'm all for using a style guide, particularly Google's since it's purpose-built. But inevitably issues fall through the cracks, and these should head straight to the hands of the Supreme Final Human Arbiter.

[shreyas1599]

@jaredmorgs @camerons I'm trying to open a PR for this. How does the following sound?

Avoid using acronyms. Use the spelt-out form of an acronym followed by the acronym in parentheses if it is absolutely necessary. Do this for the first mention. For every subsequent reference, use the acronym itself.

Or should I ignore the last two sentences?

Avoid using acronyms. Use the spelt-out form of an acronym followed by the acronym in parentheses if it is absolutely necessary.

And for the second part, changing this:

Use consistent language and tone throughout your docs.

to:

Use consistent language, spelling and tone throughout your docs.

[jaredmorgs]

I don't think that using acronyms or initialisms is "bad," as this text is suggesting. It is more a case of "use with care."

I remember listening to an episode of Grammar Girl podcast that suggested that if you were going to use the acronym or initialism more than five times in a document, then you take the time to abbreviate it first then use it throughout the document.

So maybe something like (don't think you need to take this suggestion verbatim):

Do not include acronyms or initialisms in your documentation without writing the spelled-out form on the first use. You can use the acronym or initialism for subsequent references.

[jaredmorgs]

Use consistent language, spelling, and tone throughout your docs.

I think this one is good (note the added oxford comma).

[emckean]

fixed in PR #125