Add commonly known acronyms to documentation guidelines exception list

[rolfedh]

Description

In our documentation, certain acronyms are universally recognized among Java developers and can be used without first being spelled out. I propose adding these acronyms to an exception list in our documentation guidelines for contributors. This update could also include modifying our Vale rules to prevent these well-known acronyms from being flagged in our documentation. Additionally, I plan to address proper nouns specific to Quarkus in a separate issue.

Proposed items that might no longer need to be spelled out:

• Contexts and Dependency Injection (CDI) (e.g., see this thread)

Implementation Ideas

No response

[quarkus-bot]

/cc @ebullient (documentation), @inoxx03 (documentation), @michelle-purcell (documentation), @sunayna15 (documentation)

[gsmet]

My 2 cents on this: I think we need to find the right balance. IMHO, Quarkus is attractive enough that it could be appealing for developers with little to no Java background. So I'm not saying we shouldn't have a list, I'm saying that we need to make sure our doc can be understood by someone who don't have the full background we would usually expect.

Pinging @maxandersen to see if he has a different take on this.

[sberyozkin]

Sure, as far as CDI specifically is concerned, I don't mind that much if the docs will always expand it as Context and Dependency Injection, I thought it could be unnecessary, but sure, if it makes it clearer for some new users then lets do it.

Maybe one option, where possible, is to have an acronym such as CDI always be represented as a link to https://quarkus.io/guides/cdi-reference, something like that.

[gsmet]

Yeah, as I said, it's all about finding the right balance. I just don't want us to suppose that we won't attract people not familiar with Java because I hope that's not true.

[rolfedh]

Thank you for your comment. I agree that we want to meet the needs of a wide range of users, including beginners.

Here are some possible options:

1. Spell out the first instance of each acronym. This option is simple and consistent, even if some acronyms are well-known to most users.
2. Use a list of exceptions. This option allows us to use some acronyms without spelling them out, but it requires more effort to create and maintain a list of agreed-upon exceptions. It also requires us to use tools or checks to ensure compliance with the list.
3. Decide on a case by case basis. This option gives us more flexibility and discretion, but it might lead to inconsistency or confusion among different writers and readers.

I favor option #1.
I am open to us deciding either way on option #2. It's "nice to have" but a bit costly compared to the value it adds.
I believe option #3 is unnecessarily costly.

What do you think of these options? Which one do you prefer and why?

[rolfedh]

cc: @sheilamjones @MichalMaler

[MichalMaler]

#1 @rolfedh