search

redhat-documentation / supplementary-style-guide

This project maintains the Red Hat supplementary style guide for product documentation that supplements the IBM Style guide
https://redhat-documentation.github.io/supplementary-style-guide/
Creative Commons Attribution Share Alike 4.0 International
34 stars 74 forks source link

Fix various style issues and typos throughout the guide #147

Open bredamc opened 2 years ago

bredamc commented 2 years ago
ndeevy commented 2 years ago

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 commented 2 years ago

Thanks @ndeevy!

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

ndeevy commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

@bergerhoffer I've made a start! Is there a way to tag the PR as "work in progress" until it's ready for review? https://github.com/redhat-documentation/supplementary-style-guide/pull/163

bergerhoffer commented 2 years ago

@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 commented 2 years ago

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

ndeevy commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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

bredamc commented 1 year ago

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

bergerhoffer commented 1 year ago

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

dfitzmau commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

@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 commented 1 year ago

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

mportman12 commented 1 year ago

@bredamc any updates on this?

CBID2 commented 1 year ago

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

bergerhoffer commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

bergerhoffer commented 1 year ago

@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 commented 1 year ago

@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

CBID2 commented 1 year ago

@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*:

Hi @bergerhoffer, I made my PR for the first checkbox. It's #374

bergerhoffer commented 1 year ago

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

CBID2 commented 1 year ago

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

I wonder how to solve 8b @bergerhoffer 🤔

bergerhoffer commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

I'll do number 21 @bergerhoffer

CBID2 commented 1 year ago

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

dfitzmau commented 1 year ago

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

https://github.com/redhat-documentation/supplementary-style-guide/pull/392

Recent IBM Cloud updates were made to the guide: https://github.com/redhat-documentation/supplementary-style-guide/pull/359 . The request for a usable IBM eServer System i term is no longer valid.

bergerhoffer commented 1 year ago

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

michellemacrh commented 1 year ago

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 commented 12 months ago

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

CBID2 commented 12 months ago

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

bredamc commented 12 months ago

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 commented 11 months ago

Box 10 has been addressed with this PR @bredamc

bredamc commented 11 months ago

@CBID2 Thank you :)

Srivaralakshmi commented 7 months ago

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

bburt-rh commented 6 months ago

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

bergerhoffer commented 6 months ago

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 commented 3 months ago

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

bredamc commented 3 months ago

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.