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?

[bredamc]

@bburt-rh Apologies for the delay :(
I will work on this issue when the master branch has been renamed to main.

[bergerhoffer]

@bredamc The branch rename is now complete, so you can feel free to resume this when you're ready. Thanks!

[dfitzmau]

Hi @bredamc . Just checking in with you on this Issue. How is the progress? A mammoth task, so thanks for taking this Issue on!

[bredamc]

Thanks for the reminder, @dfitzmau. I'd completed all of the subitems that I'd originally signed up for, but now that I know the content a little better, I'll review the other subitems to see if I can do a few more!

[Srivaralakshmi]

@bredamc That's great and thank you so much for all the involvement. Deeply appreciate it!

Any updates about the progress on this issue?

[Srivaralakshmi]

@bredamc That's great and thank you so much for all the involvement. Deeply appreciate it!

Any updates about the progress on this issue?

@bredamc Please respond. Gentle nudge : )

[bredamc]

No update @Srivaralakshmi -- still on my to-do list!

[mportman12]

@bredamc any updates on this?

[CBID2]

Hi @bergerhoffer! :) I see no one has done the first checkmark, so I'd like to work on it.

[bergerhoffer]

Hi @CBID2, that would be great! You can just delete those 6 entries that are listed. I've just confirmed that they already exist in the IBM style guide, so we do not need to list them here in ours.

We have information on how to contribute and open a pull request here: https://github.com/redhat-documentation/supplementary-style-guide/blob/main/CONTRIBUTING.md

Please let us know if you have any questions!

[CBID2]

Hi @CBID2, that would be great! You can just delete those 6 entries that are listed. I've just confirmed that they already exist in the IBM style guide, so we do not need to list them here in ours.

We have information on how to contribute and open a pull request here: https://github.com/redhat-documentation/supplementary-style-guide/blob/main/CONTRIBUTING.md

Please let us know if you have any questions!

Great

[CBID2]

To clarify, do you want me to delete the files mentioned in checkboxes 1-6 @bergerhoffer?

[bergerhoffer]

@CBID2 Not the whole files (because the files are done by letter, so all "A" terms are in a.adoc). But for each of those entries, you would go into the appropriate letter file and delete the lines for the entry.

For example, for "agnostic", you'd go into a.adoc and remove these lines:

[[agnostic]]
==== image:images/no.png[no] agnostic (adjective)
*Description*: _Agnostic_ denotes or relates to hardware or software that is compatible with many types of platforms or operating systems. For example, many common file formats (JPEG, MP3, and others) are platform agnostic. Use "neutral" instead.

*Use it*: no

*Incorrect forms*:

*See also*:

[CBID2]

@CBID2 Not the whole files (because the files are done by letter, so all "A" terms are in a.adoc). But for each of those entries, you would go into the appropriate letter file and delete the lines for the entry.

For example, for "agnostic", you'd go into a.adoc and remove these lines:

[[agnostic]]

==== image:images/no.png[no] agnostic (adjective)

*Description*: _Agnostic_ denotes or relates to hardware or software that is compatible with many types of platforms or operating systems. For example, many common file formats (JPEG, MP3, and others) are platform agnostic. Use "neutral" instead.



*Use it*: no



*Incorrect forms*:



*See also*:

Oh I see. Thanks

[bergerhoffer]

Reopening because the above PR only addressed 8a in the list

[CBID2]

Reopening because the above PR only addressed 8a in the list

I wonder how to solve 8b @bergerhoffer 🤔

[bergerhoffer]

I wonder how to solve 8b @bergerhoffer 🤔

We'd need to either clarify "this", or rewrite the sentence. We could do something like the change below to avoid using "this":

If your Apache web server configuration enables SSL security, verify that you enable only the TLSv1 protocol and disable SSLv2 and SSLv3 . This is because of to avoid the POODLE SSL vulnerability (CVE-2014-3566).

So the source for that would be:

If your Apache web server configuration enables SSL security, enable only the TLSv1 protocol and disable SSLv2 and SSLv3 to avoid the link:https://access.redhat.com/solutions/1232413[POODLE SSL vulnerability (CVE-2014-3566)].

[michellemacrh]

Hello 👋 is this issue still open/active?

I'm happy to take a look at 22 (Shadowman) and 23 (spec file) if they're still relevant.

[CBID2]

I'll do number 21 @bergerhoffer

[CBID2]

Hey @bergerhoffer. I did the PR for number #21. It's #391.

[dfitzmau]

Hi @redhat-documentation/ccs-style-council . I picked up item #12 and created the following PR that is ready for review:

#392

Recent IBM Cloud updates were made to the guide: #359 . The request for a usable IBM eServer System i term is no longer valid.

[bergerhoffer]

@michellemacrh yes, items 22 and 23 are still applicable if you want to create a PR for those. Thank you!

[michellemacrh]

Hi @redhat-documentation/ccs-style-council.

I picked up item 22 and created the following PR that's ready for review: #398

I updated the link and the link title per the request.

[CBID2]

Hi @bergerhoffer! Item 21 is done, so now I'll do 10

[CBID2]

As promised @bergerhoffer, Item 10 is done. The PR is #406

[bredamc]

I think it would be better to remove the entry altogether -- the IBM Style Guide already has an entry for "since" so we don't need the duplicated entry here. But I'll leave it to @bergerhoffer to advise :)

[CBID2]

Box 10 has been addressed with this PR @bredamc

[bredamc]

@CBID2 Thank you :)

[Srivaralakshmi]

@bredamc and @redhat-documentation/ccs-style-council Where does this one stand at the moment?

[bburt-rh]

@bredamc What's the status of the remaining items for this issue?

[bergerhoffer]

Chatted with @bredamc and she will take a look at the items left after Summit, to see if there are any others we should prioritize addressing, or if we can close out this issue.

[CBID2]

Hey @bergerhoffer and @bredamc! :) I did a pull request for item #27. It's #486. Check it out.

[bredamc]

Hey @bergerhoffer and @bredamc! :) I did a pull request for item #27. It's #486. Check it out.

@CBID2 Thank you for your PR but I think you misunderstood the original request (my fault for not spelling it out). As you can see in this comment, the original text for the "we suggest" entry mentioned using "recommend" instead. In item 27, I was requesting the removal of that text from the "we suggest" entry, and that change has since been made. I'll update item 27 to show that it's already done.