Fix various style issues and typos throughout the guide

[bredamc]

• 1. General: Several of the words listed are already included in IBM Style. Examples include "agnostic", "client side", "cloud", "colocate", "data center", "DevOps", and so on. It might be a good idea to compare the list with the latest version of the "Word usage" topic (https://www.ibm.com/docs/en/ibm-style?topic=word-usage), and update the IBM Style entries as necessary? [cbid2]

• 2. General: Search for occurrences of "UNIX" to ensure that it is always written in all uppercase letters (see the entry for "UNIX" in the "Word usage" topic https://www.ibm.com/docs/en/ibm-style?topic=word-usage#u). [Breda McColgan]
  Minor style updates related to UNIX #163

• 3. General: Search for occurrences of "may" that should be changed to "can" or "might" -- see the entry for "may" in the "Word usage" topic (https://www.ibm.com/docs/en/ibm-style?topic=word-usage#m). [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 4. General: Search for occurrences of "acronym" to ensure that they are all actual acronyms according to the IBM Style definition (https://www.ibm.com/docs/en/ibm-style?topic=grammar-abbreviations) -- many are initialisms, which are not pronounced as words. [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 5. General: Be consistent in the descriptions of related words:
  (a) Example 1: KB, MB, GB (see https://www.ibm.com/docs/en/ibm-style?topic=measurement-units#si-multiplier-prefixes and https://www.ibm.com/docs/en/ibm-style?topic=measurement-units#multiplier-prefixes-for-bits-and-bytes).
  (b) Example 2: online backup, offline backup.
  In any case, these entries might not be needed -- IBM Style already has entries for "online" and "offline" (see https://www.ibm.com/docs/en/ibm-style?topic=word-usage#o).
  [Volunteer needed]

• 6. https://redhat-documentation.github.io/supplementary-style-guide/#lead-in-sentences
  Typo: "prerequisties". [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 7. https://redhat-documentation.github.io/supplementary-style-guide/#release-notes
  (a) Maybe rephrase the Enhancement example to remove the 'Use with caution' term "resides" (see https://www.ibm.com/docs/en/ibm-style?topic=word-usage#r)?
  (b) Maybe rephrase the "Known issue" example to remove "There is"? (see https://www.ibm.com/docs/en/ibm-style?topic=medium-global-audiences)
  [Volunteer needed]

• 8. https://redhat-documentation.github.io/supplementary-style-guide/#links
  (a) Rephrase the second bullet item, to put "When not using running text," at the start of the sentence? [DONE, cbid2]
  (b) In "Example: Running text", second sentence: The pronoun "this" refers to an unstated noun (see https://www.ibm.com/docs/en/ibm-style?topic=grammar-pronouns#ambiguous-pronoun-references, fourth example). [8b Volunteer needed]

• 9. https://redhat-documentation.github.io/supplementary-style-guide/#_b
  In the "backtrace" entry, the comma after traceback should be moved after the quotation marks ("traceback", instead of "traceback,"). [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 10. https://redhat-documentation.github.io/supplementary-style-guide/#_b
  I think the "because" entry should be changed in one of the following ways:

  • Rename to "since" and move to the "s" section. I think it's the term "since" that is generally misused, not the term "because"?
  • Remove entirely, because (sic!) a "since" entry already exists in the "Word usage" topic in IBM Style.
    (see https://www.ibm.com/docs/en/ibm-style?topic=word-usage#s)
    [cbid2]

• 11. https://redhat-documentation.github.io/supplementary-style-guide/#_d
  Typo in the "DVD writer" entry: "adevice" should be "a device". [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 12. https://redhat-documentation.github.io/supplementary-style-guide/#_i
  ISeries (noun): The text in the iSeries entry is confusing. The incorrect term ("iSeries") is used, but it is given the green icon, and "Use it" is set to "Yes".
  A few corrective actions are required (see the pSeries and zSeries entries for comparison):
  (a) The name for the "good" entry should be changed to the approved name "IBM eServer System i".
  (b) A "Do not use" entry should be added for "iSeries" (note that the first letter should be lowercase).
  [DarraghF] item-12-147 #392

• 13. https://redhat-documentation.github.io/supplementary-style-guide/#_i
  IT, I.T. (noun): For clarity, insert a comma after "are used". Otherwise, the reader might misread the text as "all uppercase letters are used to clarify" instead of "Use ... with periods ... to clarify". [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 14. https://redhat-documentation.github.io/supplementary-style-guide/#_k
  KB (noun): Typo: "acromym" (in any case, it's an initialism, not an acronym). [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 15. https://redhat-documentation.github.io/supplementary-style-guide/#_m
  media (noun): Currently includes "diskettes" as an example, but other entries suggest that "diskette" should not be used -- we should be consistent?
  If necessary, perhaps suggest a change to the existing IBM Style advice re. "floppy disk" and "diskette"? [Volunteer needed]

• 16. https://redhat-documentation.github.io/supplementary-style-guide/#_n
  numbers (adverb): Some of the examples are labelled with "for example", and some are not -- should be consistent? [Volunteer needed]

• 17. https://redhat-documentation.github.io/supplementary-style-guide/#_p
  PC (noun): This entry refers to IBM Style for further information, but I'm not sure where in IBM Style such information is provided? [DarraghF]
  item-17-147 #408

• 18. https://redhat-documentation.github.io/supplementary-style-guide/#_p
  pop-up (noun): See the advice in IBM Style (https://www.ibm.com/docs/en/ibm-style?topic=elements-ui#menu). [Volunteer needed]

• 19. https://redhat-documentation.github.io/supplementary-style-guide/#_r
  return (verb): Use initial capitals for key names (see https://www.ibm.com/docs/en/ibm-style?topic=elements-keyboard-keys#key-names). [Volunteer needed]

• 20. https://redhat-documentation.github.io/supplementary-style-guide/#_r
  rollout (noun): The "See also" section refers to an entry that doesn't exist -- the "roll-out" entry links back to the original ("rollout") entry. [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 21. https://redhat-documentation.github.io/supplementary-style-guide/#_s
  segmentation fault (noun): In the last sentence, incorrect placement of "Only" (see https://www.ibm.com/docs/en/ibm-style?topic=grammar-adverbs-only)? Perhaps rephrase as follows: 'Do not use the abbreviation "segfault" unless absolutely necessary, ...' [cbid2]

• 22. https://redhat-documentation.github.io/supplementary-style-guide/#_s
  Shadowman (noun): In the "See also" section, maybe link directly to the page that refers to Shadowman (https://www.redhat.com/en/about/brand/standards/history) instead of to the top-level brand page (https://www.redhat.com/en/about/brand/standards)? [MichelleM]

• 23. https://redhat-documentation.github.io/supplementary-style-guide/#_s
  spec file (noun): Should the references to "RPM" be changed to "RPM package" (see https://www.ibm.com/docs/en/ibm-style?topic=elements-files-directories, sixth bullet point)? [DarraghF]

• 24. https://redhat-documentation.github.io/supplementary-style-guide/#_s
  straightforward (adjective): Should the usage advice be changed to "Use with caution", similar to the entry for "easy" in the "Word usage" topic (see https://www.ibm.com/docs/en/ibm-style?topic=word-usage#e)? [Volunteer needed]

• 25. https://redhat-documentation.github.io/supplementary-style-guide/#_t
  thin-provisioned (adjective): The "Incorrect forms" section includes the correct form ("thin-provisioned") as the first entry. [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 26. https://redhat-documentation.github.io/supplementary-style-guide/#_u
  uninterruptible (adjective): Typo: "uninterruptable". [Breda McColgan]
  Typos, acronyms, and punctuation within quotation marks #166

• 27. https://redhat-documentation.github.io/supplementary-style-guide/#_w
  we suggest (verb): We might want to remove the references to "recommend" (see https://www.ibm.com/docs/en/ibm-style?topic=information-claims-recommendations, seventh bullet point)? [bergerhoffer]

[ndeevy]

Looks like great improvements and suggestions @bredamc
Some product teams might like to weigh in on changes to their sections because conventions can vary depending on the products' upstream communities and how they like to do things.

[bredamc]

Thanks @ndeevy!

Can you please advise which items should be referred for consultation, and suggest who should be consulted?

[ndeevy]

Sure :-]
Once the changes are in a PR we can see what's what, review with the larger group, and people can jump in if they have alternative suggestions from product areas too.

[bergerhoffer]

I updated the issue to add checkmarks (so that we can mark which ones have been taken care of vs. still need to be done) and also added a [Volunteer needed] spot on each, so that we can break these up and decide who can do which updates.

@bredamc were you interested in submitting a pull request for some of these items, or would you rather someone else on the team work on them?

I'd recommend to start on some of the ones that are pretty straightforward (such as 2, 3, 4, 6, 9, 11, 14, 20, 25, 26).

We will bring this up at the next SSG meeting (Feb 23) and look for volunteers to help with the whole list. Thanks again for doing this thorough review!

[bredamc]

Thanks @bergerhoffer! I'm happy to work on them, now that I'm a little more proficient at working with Git forks :)
Should I wait until they are discussed at the meeting, or make some changes before then?

[bergerhoffer]

@bredamc It's up to you! I think that you could safely submit a PR for the numbers I mentioned above, and we can tackle the others in separate PRs, if they need additional discussion. Or if you'd prefer to wait until after the meeting, that's totally fine too.

[bredamc]

@bergerhoffer I've made a start! Is there a way to tag the PR as "work in progress" until it's ready for review?
#163

[bergerhoffer]

@bredamc Awesome! And yes, you can add a [WIP] to the beginning of the PR title. If you can add labels, you could also add the "On hold" label.

[bergerhoffer]

@bredamc I've taken a closer look at the rest and here are my thoughts on the ones that are left:

• (1) Yes, we definitely don't want to be duplicating terms that are already covered in the ISG (unless we are deviating from the suggested guidance). +1 for removing the duplicate terms you identified
• (5) I don't think I follow what you're recommending about KB/MB/GB being inconsistent. But I say to go ahead with the suggested change in a PR and we can review. I'd also be okay with you making offline backup and online backup more parallel.
• (7) These examples have recently been revamped. Can you take another look to see if there are still any lingering issues? And if so, feel free to make the suggested changes in a PR
• (8) +1 for 8a. +1 for 8b if you're able to come up with a suggestion. If not, we can ping the team to figure it out.
• (10) +1 I think we could just remove "because" all together here since (:wink:) "since" is in the ISG
• (12) I honestly don't know what to do about this one 😄
• (13) I think you did this one already
• (15) I think we could safely remove "diskettes" from the list here, since it's just an example.
• (16) I'd be okay with however you want to update to make them more consistent. This one is a little rough to read in such a large block, but we can't use bullets/formatting in these descriptions to break it up nicer. Though honestly I'd be curious to know whether any of this actually deviates from what the ISG recommends. If not, we could consider pulling it completely.
• (17) I think we could just remove the "See" sentence
• (18) I feel like we could remove this. I think that if pop-up is going to be used, then it should be qualified as a pop-up window or pop-up list as the ISG recommends. (Similar to drop-down)
• (19) I can't tell for sure, but it seems like this entry is implying that the enter key is actually listed lowercase "enter" on a Mac. I'd have to understand a little more to be able to make a recommendation.
• (21) I'm fine with your reword suggestion
• (22) +1
• (23) +1
• (24) If we wanted to change it to with caution, I think we'd need to specify in the description why. Feel free to make a suggestion here
• (27) Possibly, but I'm unsure how it would look once removing.

[ndeevy]

I agree with all your suggested changes Breda, and Andrea's assessments. Kudos and thanks :-]

One thought about (27), we could just cut off the 'recommend' like:
Do not use "we suggest". Use a more direct construction or use "recommend". For example, instead of "We suggest that you make a backup of your data disk", write "Back up your data disk".

'Recommend' is kind of a tricky in itself, I see it come up in our docs a lot, but IBM doesn't speak directly to it alone -do you both think it could warrant its own entry?

[bredamc]

Thank you, Andrea and Naomi!

I've reviewed your suggestions, Andrea:
(7). I've removed 7(c) ("In the "Deprecated functionality" section, is it correct to say "Red Hat do not implement" (two occurrences), or should it be "Red Hat does not implement"? "), but 7(a) and 7(b) are still valid.
(12) I can create a PR with a suggestion, but I wonder why these sections are included at all? Are these terms used in RH docs? Should we maybe request the addition of these terms to IBM Style instead?
(13) I did indeed do this one already! Apologies for not updating it at the time, I've updated it now.
(16) I'll review again to see if any of the advice is different from that in IBM Style.
(19) I think the IBM Style advice is to use an initial capital for the key name, regardless of the hardware used. The "Keyboard keys" topic includes the following Mac example: "Press Return."

I agree with your other recommendations, and am happy to work on them. Do we need to notify the Council about the sections that we propose to remove, or is it time enough to notify when requesting PR approval?

[bergerhoffer]

@bredamc Responses inline!

(12) I can create a PR with a suggestion, but I wonder why these sections are included at all? Are these terms used in RH docs? Should we maybe request the addition of these terms to IBM Style instead?

Good question. I don't know enough about these terms to know whether/where in RH docs they are used. But if they are included here, I would assume that someone had a need for them. But I would say that the best outcome would be for these terms to be in the ISG, if we want to ask them.

(19) I think the IBM Style advice is to use an initial capital for the key name, regardless of the hardware used. The "Keyboard keys" topic includes the following Mac example: "Press Return."

I would +1 the standardization of capitalizing the keys (especially since we don't always know what OS people are on). I'd say that we could probably remove both the "enter" and "return" entries, in favor of following the ISG.

I agree with your other recommendations, and am happy to work on them. Do we need to notify the Council about the sections that we propose to remove, or is it time enough to notify when requesting PR approval?

I think that requesting review/approval from the council during the PR review should be fine!

[bburt-rh]

@bredamc When you get a chance, could you please update the status of this issue?