Adding information about posessives #519
Conversation
There was a problem hiding this comment.
Thanks Christine, this is great. I have a couple of suggestions:
- Remove contractions. We don't use them in RH docs and we like our style guide to follow our own rules (even if commit and revew messages don't :) )
- I'd avoid saying "the best source". How about "one of the best sources"? As soon as we introduce absolutes we need to be able to back them up with data.
Other people might have comments as well.
Done @daobrien |
|
@CBID2 Christine, Many thanks for your contribution, much appreciated!
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? |
|
Looks great @julian-cable! 😊 |
There was a problem hiding this comment.
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!
en-US/Grammar.xml
Outdated
| For guidance on how to form a possessive, see <xref linkend="apostrophes"/>. | ||
| </para> | ||
| <para> | ||
| Consider the following scenarios for when to use or not to use a possessive: |
There was a problem hiding this comment.
I suggest deleting this line. What follows is both guidance and scenarios, but instead of updating the sentence to correct this, it could just be deleted.
en-US/Grammar.xml
Outdated
| Consider the following scenarios for when to use or not to use a possessive: | ||
| </para> | ||
| <para> | ||
| Do not use possessives to refer to abbreviations or product names. |
There was a problem hiding this comment.
The current sentence provides guidance on two different topics in one statement (abbreviations and product names). For clarity, I suggest separating the topics with their respective examples. From an information design standpoint, combining guidance can make it harder for readers to find the information they need. For example, I suggest starting with "Do not use possessives with product names." followed by the examples with product names. Then, "Do not use possessives with abbreviations." followed by the examples with abbreviations.
There was a problem hiding this comment.
Can you give me an example @rclee33? I had trouble with formatting.
en-US/Grammar.xml
Outdated
| Consider the following scenarios for when to use or not to use a possessive: | ||
| </para> | ||
| <para> | ||
| Do not use possessives to refer to abbreviations or product names. |
There was a problem hiding this comment.
Since abbreviations are mentioned here, I suggest updating the relevant section, 3.6. Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly, with this guidance as well. That section is currently being updated, but I suggest adding the lines: "Do not use possessives with abbreviations. For examples and more information, see ." I'm tagging @julian-cable because he has worked on that section.
Point of discussion: should this guidance be expanded to include initialisms? If yes, we could say: "Do not use possessives with abbreviations and initialisms" followed by the link to the new possessives section.
There was a problem hiding this comment.
We should also add a third piece of guidance with examples: "Do not use possessives with company names." followed by examples. Putting my previous suggestions together, I suggest ordering the guidance in this section (with their examples) based on its relevance to Red Hat training materials: company name, product names, abbreviations.
There was a problem hiding this comment.
@julian-cable, I might need your help with this
| @@ -1058,6 +1058,11 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest | |||
|
|
|||
| <!-- <listitem> | |||
| </listitem> --> | |||
| <para> | |||
| Do not use possessives to refer to product names. | |||
There was a problem hiding this comment.
At line 1046, I suggest adding the following lines: "Do not use possessives with the Red Hat company name. For examples and more information, see .
Rationale: Section 3.7 first discusses using the company name, followed by how to use product names. Likewise, the new guidance about possessives should follow this same structure. (And this follows a best practice of covering one topic at a time when providing guidance.)
There was a problem hiding this comment.
I spoke with Julian about this, and we're going to wait on guidance around possessives and company names. Because of that, I rolled back this suggestion. Sorry about that!
Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com>
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. |
|
Thanks for solving them @rclee33 |
|
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 |
|
@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. |
Things look great now @rclee33. |
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. |
|
@CBID2 Very cool! Yes, I'm on linkedin: https://www.linkedin.com/in/rachelclee33 |
julian-cable
dismissed
daobrien’s stale review
Requested changes have been implemented.
* Working on #450. * Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. * Ongoing updates for #456 * Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. * s/may/might/ per Julian's review. * Working on #457 Run Vale of the style guide part 3. * Closes #457 Run Vale over the style guide, part 3. * Remove spurious space. * Closes #458 Run Vale over style guide part 4. * Closes #365 Remove DocBook references. * Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. * Closes #355. Improve a bit of formatting. * feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits * Updated guidance on continuation prompts (#494) * Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix * Updated IBM Style access info (#496) * Updated term entries (#497) * Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix * Updated sample names and other small fixes (#502) * Various fixes (#512) * Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment * Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback * Updated audience description (#518) * Updated audience description * Further updated audience wording * Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable <jcable@redhat.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * Updated view and edit files section * Added release notes for 6.1 and updated version information (#522) * updating homepage (#525) --------- Co-authored-by: daobrien <noreply@solaris.milky.way> Co-authored-by: David O'Brien <daobrien@users.noreply.github.com> Co-authored-by: mweetman-redhat <mweetman@redhat.com> Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Harpal Singh <52556240+harpasin@users.noreply.github.com>
* Working on #450. * Run Vale over Design.xml. This is the end of part 1/4 of "Run Vale over the style guide." Too big a job to try to handle in one issue and PR. * Ongoing updates for #456 * Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. * s/may/might/ per Julian's review. * Working on #457 Run Vale of the style guide part 3. * Closes #457 Run Vale over the style guide, part 3. * Remove spurious space. * Closes #458 Run Vale over style guide part 4. * Closes #365 Remove DocBook references. * Closes #78 Update entry for "virtualized". Basically copy/paste from corp guide. * Closes #355. Improve a bit of formatting. * feat: Add advice on naming the default branch in an inclusive way. (#493) * feat: Add advice on naming the default branch in an inclusive way. * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Update en-US/Language.xml Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Updated section about writing titles (#492) * Updated section about writing titles * Reverted title ID * Further edits * Updated guidance on continuation prompts (#494) * Various fixes for 6.1 release (#495) * Various fixes for 6.1 release * XML fix * Updated IBM Style access info (#496) * Updated term entries (#497) * Added guidance on omitting part of an output (#500) * Added guidance on omitting part of an output * Updated wording * Typo fix * Updated sample names and other small fixes (#502) * Various fixes (#512) * Implementing various feedback suggestions from Rachel (#513) * Implementing various feedback suggestions from Rachel * Addressed review comments * Addressed further review comment * Added more punctuation guidance (#515) * Added more punctuation guidance * Implemented review feedback * Updated audience description (#518) * Updated audience description * Further updated audience wording * Adding information about posessives (#519) * feat: added section about posessives * feat: here's the actual section * fix: made some revisions * Content and formatting updates * Update en-US/Punctuation.xml Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * fix: made some revisions * fix: made another revision * Removed company name and restructured section * added link in section 3.6 * Final XML fix --------- Co-authored-by: Julian Cable <jcable@redhat.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> * Updated view and edit files section * Added release notes for 6.1 and updated version information (#522) * updating homepage (#525) * 6.2 quick fixes (#544) * Some updates concerning punctuation (#545) * Updated guidance for punctuation and special characters * Enhanced guidance about punctuation in lists * Minor formatting * Content and formatting * Applied feedback * Minor fixes * Word usage updates: screenshot, lookup, see/refer to (#546) * Word usage updates: screenshot, lookup, see/refer to * Addresses one comment * Updates to see/refer to entries * Minor fix * Line continuation for multiple operating systems (#548) * Line continuation for multiple operating systems * Minor edit * Add 64-bit architecture guidance (#547) * Add 64-bit architecture guidance * Implementing edits from review * Updated Boolean guidance and a bug fix (#551) * Updated Boolean guidance and a bug fix * Update to Boolean entry * Reworked entries for tar, tarball, untar, unzip, zip (#552) * Clarify capitalization for table titles (#553) * Updates on referring to object names and using realistic usernames (#554) * Updates on referring to object names and using realistic usernames * Apply review comments * Updates for apostrophes and quotation marks (#557) * Updates for apostrophes and quotation marks * Updated list of punctuation marks * Updated guidance about titles (#559) * Updated guidance about titles * Change 'book' to 'publication' * Footnote update (#560) * adding ulink tag to a url * Replace an invalid URL --------- Co-authored-by: Julian Cable <jcable@redhat.com> * fix(docs): add some build instructions (#562) * fix(docs): add some build instructions * feat: add build shortcut * Added small comment --------- Co-authored-by: julian-cable <jcable@redhat.com> * Corrected some titles to use title case (#563) * Add release notes and update version info (#564) * Add release notes and update version info * Minor wording fix --------- Co-authored-by: daobrien <noreply@solaris.milky.way> Co-authored-by: David O'Brien <daobrien@users.noreply.github.com> Co-authored-by: mweetman-redhat <mweetman@redhat.com> Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Harpal Singh <52556240+harpasin@users.noreply.github.com> Co-authored-by: Alex Corcoles <alex@pdp7.net>
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.