search

StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
71 stars 20 forks source link

Adding information about posessives #519

Closed CBID2 closed 1 year ago

CBID2 commented 1 year ago

Problem

The style guide needs information about effectively using possessives.

Changes

This PR adds a new section to the Grammar.xml file called "Possessives". It provides guidelines on when to use possessives and when to avoid using them.

Closes

Closes #517

Note to Reviewers

I'm open to feedback on how to change the formatting.

CBID2 commented 1 year ago

one of the best sources

Done @daobrien

julian-cable commented 1 year ago

@CBID2 Christine, Many thanks for your contribution, much appreciated! I have pushed some further changes as follows:

Any further comments are welcome.

CBID2 commented 1 year ago

@CBID2 Christine, Many thanks for your contribution, much appreciated!

I have pushed some further changes as follows:

  • Referring to the "Apostrophes" section for how to form a possessive, which is already described there.

  • Added a further example of a possessive to use a Red Hat product name.

  • Added references to the new "Possessives" section from two other relevant sections (per Rachel's comments).

  • Resolved an XML tagging mismatch to build correctly.

Any further comments are welcome.

You're welcome @julian-cable! 😊 Are you saying that these are changes I need to add or ones that you pushed to my pull request?

julian-cable commented 1 year ago

@CBID2 I pushed my proposed updates to your PR: https://github.com/StyleGuides/WritingStyleGuide/pull/519/commits/4d6027784381906c223e33e17161b4e23268d660

CBID2 commented 1 year ago

@CBID2 I pushed my proposed updates to your PR: https://github.com/StyleGuides/WritingStyleGuide/pull/519/commits/4d6027784381906c223e33e17161b4e23268d660

Looks great @julian-cable! 😊

CBID2 commented 1 year ago

Thank you, @CBID2, for contributing this guidance! These changes will provide important clarification when it comes to using possessives in technical content. I've made suggestions on the PR -- please let me know if you have any questions or if there's anything we should discuss further. Thank you!

Thanks for your feedback @rclee33. Can you put some of them as in-line comments though? I'm trying to visualize the formatting but it's not quite clicking.

CBID2 commented 1 year ago

Thanks for solving them @rclee33

rclee33 commented 1 year ago

Hi @CBID2! Feel free to push your most recent changes. I've cloned your fork and will implement my suggestions in a separate commit for you and @julian-cable to review.

CBID2 commented 1 year ago

Hi @CBID2! Feel free to push your most recent changes. I've cloned your fork and will implement my suggestions in a separate commit for you and @julian-cable to review.

Hi @rclee33! I only implemented your suggestion for line 1046

rclee33 commented 1 year ago

@CBID2 @julian-cable I just pushed my commit -- hopefully, I did that correctly! =)

Julian and I talked about my suggestions about using possessives with company names and we decided to wait on adding this to the style guide. I rolled back that addition -- sorry about that!

Another change I made was to restructure the "Possessives" section so that product names and abbreviations are covered separately. I also reordered the examples to begin with Red Hat (order of importance).

Finally, I added a cross-reference in section 3.6 to the new possessives section.

CBID2 commented 1 year ago

@CBID2 @julian-cable I just pushed my commit -- hopefully, I did that correctly! =)

Julian and I talked about my suggestions about using possessives with company names and we decided to wait on adding this to the style guide. I rolled back that addition -- sorry about that!

The other change I made was to restructure the "Possessives" section so that product names and abbreviations are covered separately. I also reordered the examples to begin with Red Hat (order of importance).

Things look great now @rclee33.

CBID2 commented 1 year ago

@CBID2 @julian-cable I just pushed my commit -- hopefully, I did that correctly! =)

Julian and I talked about my suggestions about using possessives with company names and we decided to wait on adding this to the style guide. I rolled back that addition -- sorry about that!

Another change I made was to restructure the "Possessives" section so that product names and abbreviations are covered separately. I also reordered the examples to begin with Red Hat (order of importance).

Finally, I added a cross-reference in section 3.6 to the new possessives section.

By the way @rclee33, are you on Linkedin and Twitter? I'm doing this open source challenge and I want to give you a shout-out in my post.

rclee33 commented 1 year ago

@CBID2 Very cool! Yes, I'm on linkedin: https://www.linkedin.com/in/rachelclee33

julian-cable commented 1 year ago

@CBID2 @rclee33 Thanks both very much indeed for your significant contributions to this effort! I am now approving this PR.