OpenStack -> RHOSP in ShiftStack IPI docs

[maxwelldb]

Based on discussion and resulting PM clarification here: #16985 (comment)

Related to https://jira.coreos.com/browse/OSDOCS-470

For 4.2.

[maxwelldb]

@bergerhoffer @lamek @bobfuru This needs a look and merge. L size, but it's all just name changes.

[maxwelldb]

And yes, "a RHOSP" might read a little strangely, but it seems to be more commonly used in the OSP docs than "an RHOSP," so I'm sticking with it for now.

[bobfuru]

A few very small suggestions.

[bobfuru]

LGTM!

[bobfuru]

/cherrypick enterprise-4.2

[openshift-cherrypick-robot]

@bobfuru: new pull request created: #17309

In response to this:

/cherrypick enterprise-4.2

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[bergerhoffer]

@maxwelldb Yes "a RHOSP" does sound wrong to me. Where did you look? I just opened a few RHOSP docs and didn't see any references at all to either "a RHOSP" or "an RHOSP".

"an RHOSP" would be the correct way, or just spell it out.

[maxwelldb]

@bergerhoffer I found it most often in the OSP Certification docs, e.g. https://access.redhat.com/documentation/en-us/red_hat_openstack_certification/1.0/html/red_hat_openstack_application_and_vnf_workflow_guide/publishing-a-rhosp-application-certification.

The mainline OSP docs seem to avoid the abbreviation almost entirely, though they also frequently violate the product naming guidelines, e.g. using "OpenStack Platform" rather than the full name or acronym. You can find the occasional "an RHOSP" in there, though.

AFAIK, IBM guidelines say to stick with "a" if it's pronounced something like "rossp" and "an" if it's an initialism. I assumed from the frequency of "a RHOSP" vs. "an RHOSP" on redhat.com that it's not the latter, but that's admittedly just from a Google search.

[bergerhoffer]

@maxwelldb It's not a critical issue, though I still think it sounds bad. I checked with the OpenStack DPM who says that their guidance is to typically write out the full name (he says they have ~900 instances written out and only a handful of RHOSP in the latest.

For our purposes, I think we should just write the full name out every time, especially for as infrequently as it is used. We should probably add things like this as attributes in the common-attributes.adoc file.

[maxwelldb]

@bergerhoffer I don't think writing it out every time is a good move. The phrase would appear dozens of times per assembly, and it's kind of cumbersome as it is--especially since it's frequently paired with {product-title}.

I think it would be good to get the OSP DPM to align with the master product and solution naming list: https://docs.google.com/spreadsheets/d/1DLS_lS3VKidgZIvcLmLp9BoiqptkvqHWfe1D5FD2kfk/edit#gid=1987148185

We could clarify the guidance that's there, and then we could use the result of that to update common-attributes.adoc.

[bergerhoffer]

@maxwelldb The master naming spreadsheet says that we can use RHOCP in technical documentation, but we don't.

[maxwelldb]

@bergerhoffer And that's something that I'm discussing with Vikram later today, as seeing the list got me thinking. I don't think the multiple sets of guidelines floating around--formal and not--are helpful.

Those guidelines do allow RHOSP as a short name, so that's what I used.

[bergerhoffer]

@maxwelldb Sure. If the OSP docs don't use those guidelines, then it probably shouldn't say that in the spreadsheet for other teams to use. Same with RHOCP.

Either way, they should also add guidance on the "a" vs. "an", and the pronunciation of them. But if you do go with RHOSP in our docs, then I think you should use "an" unless we know for sure that they want people saying rossp.

[maxwelldb]

@bergerhoffer I can ask around to see who can correct that. Is Chuck Copello the OSP DPM?

Aside from that, it's just:

Choose the indefinite article a or an according to how the abbreviation, word, or number is spoken. Use a before an abbreviation, word, or number that begins with a consonant sound. Use an before an abbreviation, word, or number that begins with a vowel sound.

According to page 10 of the latest IBM Style Guide. I'd imagine that the OpenStack folks might be forced to declare a preference that hasn't yet been decided.

[bergerhoffer]

Yep to Chuck. And about the "hasn't yet been decided" part, that's why I'm suggesting writing it out in our docs, so we're not making that decision. And because we don't know the answer to how it's spoken, if we have to make a choice, I would think the safest option would be to assume that it is spoken spelled out R-H-O-S-P.

[bergerhoffer]

@maxwelldb Or is there any way that we can just write around it? Using "the" instead of "a" or "an", etc.?

[maxwelldb]

@bergerhoffer Chuck said that they're currently in the midst of a style consistency review that'll solve "a" vs. "an," but to use "an RHOSP" for now.

I'll make a PR to update for that and the common attributes file presently.