Revisit list of acronyms

[colleenmcginnis]

Context: I've been testing these rules against existing docs to identify problematic patterns that we might be able to fix before a larger rollout.

There are probably some acronyms (or words that are in ALL CAPS that are currently being interpreted as acronyms by the linter) that we should add to the list of exceptions in Acronyms.yml. Here are the results: acronyms (summary).

It looks like in 9312937 (I think this was committed to main without a PR) added most (all?) of the acronyms found in the existing docs. However, I don't think we want to add all of them to the list of exceptions because then there's not really any value to the acronym rule.

Writers should look critically at the list of existing acronyms to:

• Identify acronyms that we're comfortable assuming readers already know and add them to the list of exceptions.
• Identify words that are in ALL CAPS that are currently being interpreted as acronyms and should be allowed to continue to be in ALL CAPS without definition. Then add them to the list of exceptions.

In my opinion (but you may disagree with me!) the benefits of this approach justify the time and effort it would take to review the list of acronyms critically. The benefits include bulk-updating the list of exceptions ahead of a larger rollout so writers don't have to add as many one-off exceptions later and reducing noise for developers after the rollout (which IMO will help us build goodwill across the engineering org or at least not lose any :)).

cc @theletterf

[theletterf]

Agh, yes, I saw the spreadsheet first and added them all to the existing rule. Which is probably overkill. (For the Capitalization rules, I would add as many as possible though).

I think most of the acronyms could be added to the list of exceptions, especially if they have a certain presence in the docs already; chances are that they might have been defined already. If we followed this method:

• What could be a good cutoff criterion? 20 hits?
• Could you run a search for those acronyms and see if they're wrapped in parentheses?

But I'm open to pushback here, roll back, and go for a thorough analysis of which ones should be added.

Edit: I reverted the experimental commit here 87d7c0a. The existing lists contains ESQL reserved words that Florent reported as false positives. The next commit will be through a PR so we can review the list together.

[colleenmcginnis]

What could be a good cutoff criterion? 20 hits?
Could you run a search for those acronyms and see if they're wrapped in parentheses?

I'm not sure this is the right way to think about it. I think we should think from the user perspective. As @bmorelli25 mentioned, it would probably be beneficial to facilitate a structured rule feedback discussion. As a part of that, we could get feedback from writers on a couple questions:

• Individual acronyms: For each individual acronym used in the docs you own, are you comfortable assuming readers will know what it means? Is it a well-known industry term? Is it a well-established Elastic product or feature? If not, it should be defined in our docs.
• General guidelines: For acronyms we can't assume users will know, how prominent should the acronym definition be? Is it important to define the acronym on every page (probably yes if we are taking an every-page-is-page-one model)? If not, what is the guideline and can we test it (we might not be able to if it's not page-based)?

I think doing the work related to the first item will inform the second.

[theletterf]

If I'm not mistaken, the original issue originated because of the Acronyms rule being too "noisy", but still marking correctly undefined acronyms. If we leave as it is now and add exceptions iteratively, we're protecting the reader of the docs by default, while perhaps mildly irritating the user of Vale -— the writer.

As nice as the structured feedback approach sounds, that would mean answering two/three questions for 1375 acronyms. For an average of 20 to 30 seconds per acronym, that could easily take 8 to 10 hours for a writer to review the entire list. But even if a writer feels comfortable with an acronym, another might not, either due to lack of familiarity with the concept or the area, with the result that a negative would be enough to discard the acronym from the list of exceptions.

If you think this might be time well spent upfront, we can prepare a small feedback tool / sheet and recruit writers from each area to do a rating run.

[colleenmcginnis]

As nice as the structured feedback approach sounds, that would mean answering two/three questions for 1375 acronyms. For an average of 20 to 30 seconds per acronym, that could easily take 8 to 10 hours for a writer to review the entire list.

Apologies. I didn't expect every writer to literally do this one-by-one for every acronym. I think what's important is facilitating a discussion among writers. That might mean taking the 100 most commonly used acronyms, the person facilitating the discussion to make some suggestions ahead of the discussion, and then use the discussion get insight into how people are thinking about this topic. For example, a brief team-wide discussion (could just be async) on whether we need to define ECS on every page could help reduce a LOT of noise.

This would help us write more specific acronyms guidelines that writers feel some ownership over rather than: (1) one or two people making decisions for all writers, (2) writers just getting into the habit of ignoring Vale suggestions because it's annoying to add one exception and wait for a release for it to be implemented, or (3) writers adding acronyms to the exception list to fit one context but impacting all docs.

I think this about more than reducing noise (though that is important!). It's also about writers feeling like we're creating these rules together. I liked how @bmorelli25 put it: that we're all going to be impacted by this change so we all should feel comfortable defending the rules that the linter suggests.

[theletterf]

Thanks for clarifying! I agree with you that this is something we should all feel proud of (around 10 writers already contributed commits and issues to this repo — we want to get to all).

I'll think of an async activity we could do around your list (which is great, by the way), with writers contemplating the general view and thinking about how to go about it. As you wrote before, this would inform other actions.

Open to suggestions on how to set this up (you've a knack for organizing practical activities).