Update references to IBM Style with links, and remove marketing references #609
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This was
linked to
issues
Sep 4, 2024
Closed
rclee33
reviewed
Sep 4, 2024
Contributor
rclee33
left a comment
rclee33
left a comment
There was a problem hiding this comment.
I've completed my review! Let me know if you have any questions, or if anything here warrants further discussion.
README.md
Outdated
| It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases. | ||
|
|
||
| It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. | ||
| It is based on IBM Style but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. |
Contributor
There was a problem hiding this comment.
Suggested change
| It is based on IBM Style but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions. | |
| It is based on IBM Style but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (18th Ed.) for further grammatical and style decisions. |
Contributor
There was a problem hiding this comment.
I updated the CMS edition to 18.
Here and throughout, I suggest using only one spelling reference -- I've seen Merriam-Webster mentioned as our standard source (in Confluence), but not American Heritage. I suggest using only M-W.
Below, I also suggest using the publicly available Merriam-Webster.com dictionary (https://www.merriam-webster.com/) over the Unabridged version (https://unabridged.merriam-webster.com/), which requires a subscription.
Contributor
There was a problem hiding this comment.
Is it really the case that this style guide is "based on" IBM Style? I thought that this style guide pre-dated IBM's acquisition of Red Hat?
At any rate, consider updating this blurb to align with the similar, but different blurb on the site: https://stylepedia.net/
en-US/Audience.xml
Outdated
| </para> | ||
| <para> | ||
| Other resources for technical writing are listed in <xref linkend="resources"/>. | ||
| Of these resources, <citetitle>IBM Style</citetitle> is now available for Red Hat employees to access online, but does not have a wider circulation. |
Contributor
There was a problem hiding this comment.
Suggested change
| Of these resources, <citetitle>IBM Style</citetitle> is now available for Red Hat employees to access online, but does not have a wider circulation. | |
| Of these resources, <citetitle>IBM Style</citetitle> is available for Red Hat employees to access online, but does not have a wider circulation. |
Contributor
There was a problem hiding this comment.
No need to anchor this statement in a specific point of time. "Now" will quickly become out of date! =D
Contributor
There was a problem hiding this comment.
In cases where we mention "IBM Style" in general, what do you think about also providing a link to the homepage at https://www.ibm.com/docs/en/ibm-style? Currently, these references are styled as titles, but I'm wondering whether it would be more effective for our style guide (an online resource) to use hyperlinks for references that are also online resources.
Rationale: Hyperlinks help users get the information that they need, at their point of need. Even for general mentions, including a link would be helpful.
For example:
Of these resources, IBM Style 🔒 is available...
en-US/C.xml
Outdated
| </para> | ||
| <para> | ||
| Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for more information. | ||
| Refer to the Word Usage chapter of <citetitle>IBM Style</citetitle> for more information. |
Contributor
There was a problem hiding this comment.
I'm not sure whether this matters, but IBM Style refers to this section a "list", rather than a chapter ("The following list provides..."). To align with IBM terminology, perhaps we could say: "Refer to the Word Usage list in..."
Or, perhaps we could use a more generic term like "section". ("Chapter" strikes me as rather bibliocentric, which might not make sense in an online resource. Signed, a bibliophile. =)
Just noting that if we make any change here, we'd need to update throughout.
Collaborator
Author
There was a problem hiding this comment.
I like "section".
en-US/Resources.xml
Outdated
| The guides that you refer to first are generally dictated by the type of material that you are writing. It is important to establish this point first because the guidelines in the following references sometimes contradict each other. It does not mean that the guidelines are wrong; different audiences require different writing styles, and different references are sometimes required when you change styles. | ||
| </para> | ||
| <para> | ||
| The following documentation types are within the scope of this guide: |
Contributor
There was a problem hiding this comment.
Suggested change
| The following documentation types are within the scope of this guide: | |
| The following technical content types are within the scope of this guide: |
Contributor
There was a problem hiding this comment.
Some of these examples would not be considered "documentation" - I suggest using a more general descriptor in the lead-in sentence.
| The following documentation types are within the scope of this guide: | ||
| <itemizedlist> | ||
| <listitem> | ||
| <para> |
Contributor
There was a problem hiding this comment.
I suggest removing the categories of "Technical content" and "Technical collateral", and use a bullet for each content type in alphabetical order. For example:
- Software manuals and documentation
- Technology briefs
- Training courses
- User guides
- White papers
Contributor
There was a problem hiding this comment.
PS. What's a "technology brief"? Is that marketing-related, and could it be removed?
en-US/Translation.xml
Outdated
|
|
||
| <para> | ||
| The following discussion provides some initial insight into using lists correctly. Refer to the <citetitle>IBM Style Guide</citetitle> for a full discussion. | ||
| The following explanation provides some initial insight into using lists correctly. |
Contributor
There was a problem hiding this comment.
Suggested change
| The following explanation provides some initial insight into using lists correctly. | |
| This section provides some initial guidance for using lists correctly. |
en-US/Design.xml
Outdated
| Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)". | ||
| Not all acronyms are capitalized (for example, "spool"); refer to the <citetitle>IBM Style Guide</citetitle> or another suitable reference if you are unsure. | ||
| Not all acronyms are capitalized (for example, "spool"); refer to | ||
| <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=grammar-capitalization#abbreviations"><citetitle>Capitalization</citetitle></ulink> in <citetitle>IBM Style</citetitle> |
Contributor
There was a problem hiding this comment.
The URL brings us to the section entitled "Abbreviations", but the linked text says "Capitalization". These should be consistent. I suggest either updating the linked text to "Abbreviations", or updating the URL to point to the parent section, "Capitalization".
en-US/T.xml
Outdated
| <para> | ||
| <emphasis>n.</emphasis> The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. Refer to the <citetitle>IBM Style Guide</citetitle> for more information about using measurements and abbreviations. | ||
| <emphasis>n.</emphasis> The amount of data that is transferred from one place to another or processed in a specified amount of time. Data transfer rates for disk drives and networks are measured in terms of throughput. Typically, throughput is measured in kbps, Mbps, or Gbps. | ||
| For more information about using measurements and abbreviations, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=measurement-units"><citetitle>Units of Measurement</citetitle></ulink> in <citetitle>IBM Style</citetitle> |
Contributor
There was a problem hiding this comment.
Suggested change
| For more information about using measurements and abbreviations, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=measurement-units"><citetitle>Units of Measurement</citetitle></ulink> in <citetitle>IBM Style</citetitle> | |
| For more information about using abbreviations for units of measurement, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=measurement-units"><citetitle>Units of Measurement</citetitle></ulink> in <citetitle>IBM Style</citetitle> |
en-US/B.xml
Outdated
| <listitem> | ||
| <para> | ||
| <emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, per AP style, even when used as a complex adjective. | ||
| <emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, even when used as a complex adjective. |
Contributor
There was a problem hiding this comment.
Suggested change
| <emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, even when used as a complex adjective. | |
| <emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, even when used as a compound modifier. |
en-US/Design.xml
Outdated
| <para> | ||
| Consider the following points when choosing a realistic name: <footnote> <para> | ||
| Examples taken from the <citetitle>IBM Style Guide</citetitle> and the <citetitle>Google Developer Documentation Style Guide</citetitle>. | ||
| Examples taken from <citetitle>IBM Style</citetitle> and the <citetitle>Google Developer Documentation Style Guide</citetitle>. |
Contributor
There was a problem hiding this comment.
This footnote seems misplaced. Ideally, this footnote would appear just after the sentence where the examples are provided. However, this footnote is attached to a lead-in sentence that does not include any examples. As a result, it is unclear which material comes from these sources. This is likely out of scope for this PR, but consider moving this footnote to the sentence with the relevant examples.
Could we phrase this more generically: "Examples adapted from" rather than "taken from"? I'm guessing that we didn't quote exact language from these sources, just adapted the example names for our discussion. But that's just a guess.
Collaborator
Author
There was a problem hiding this comment.
I've changed how and where the reference information is included here. It seems that IBM Style does not provide specific guidance here; the Google developer documentation style guide does, although no specific examples are taken from there.
rclee33
approved these changes
Sep 13, 2024
Contributor
rclee33
left a comment
rclee33
left a comment
There was a problem hiding this comment.
Fixes look good to me! Thank you for all your work making these updates!
julian-cable
added a commit
that referenced
this pull request
Oct 9, 2024
* 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 * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback --------- 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> Co-authored-by: Ashley D'Andrea <jdandrea@gmail.com> Co-authored-by: Steven Bonneville <sbonnevi@redhat.com> Co-authored-by: Rachel Lee <ralee@redhat.com>
julian-cable
added a commit
that referenced
this pull request
Nov 22, 2024
* 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 * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback * Updated audience section for Homepage (#623) * updating index page * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * updating index page for v7.0 (#624) * updating index page for the latest version * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Add dark mode enhancement to What's New (#626) --------- 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: julian-cable <79939933+julian-cable@users.noreply.github.com> Co-authored-by: Julian Cable <jcable@redhat.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Alex Corcoles <alex@pdp7.net> Co-authored-by: Ashley D'Andrea <jdandrea@gmail.com> Co-authored-by: Steven Bonneville <sbonnevi@redhat.com> Co-authored-by: Rachel Lee <ralee@redhat.com>
julian-cable
added a commit
that referenced
this pull request
Jun 3, 2025
* 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 * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback * Updated audience section for Homepage (#623) * updating index page * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * updating index page for v7.0 (#624) * updating index page for the latest version * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Add dark mode enhancement to What's New (#626) * Some maintenance updates for 7.1 (#635) * Some maintenance updates for 7.1 * Apply feedback and add release notes * A further round of maintenance updates for the 7.1 release (#641) * A further round of maintenance updates for the 7.1 release * Add dollar sign * Minor fix * Further fix * Jcable/allow object class (#643) * Update guidance for 'allow' * Add guidance for naming object classes * Implement feedback * Minor restructure and update release notes * Minor typing fix (#644) * Minor fixes for 'referring to' section --------- 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: julian-cable <79939933+julian-cable@users.noreply.github.com> Co-authored-by: Julian Cable <jcable@redhat.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Alex Corcoles <alex@pdp7.net> Co-authored-by: Ashley D'Andrea <jdandrea@gmail.com> Co-authored-by: Steven Bonneville <sbonnevi@redhat.com> Co-authored-by: Rachel Lee <ralee@redhat.com>
julian-cable
added a commit
that referenced
this pull request
Jun 4, 2025
* 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 * Remove 'check' entry (#579) * Add 'sign-in' (#580) * Add 'sign-in' * Update login, sign-in, sign-on * XML validation fixes * Implement suggestions from Ashley D'Andrea (#589) * Implement suggestions from Ashley D'Andrea * Apply feedback from Rachel * Apply feedback from Ashley * Add guidance for 'named' and 'called' (#591) * Add guidance for 'named' and 'called' * Further edit * Update guidance for 'go to' (#592) * Update guidance for 'go to' * Add a clarification * Add gitignore for untracked files (#590) * Update guidance about 'Overview' as a title (#593) * Clarify guidance for 'lifecycle' (#594) * Remove yes/no as values for Ansible 'become' * Edits to address feedback in #600 * Update en-US/Design.xml * Update en-US/Design.xml * fixes two sentences on one line * Update 'dialog box' entry (#603) * Update 'dialog box' entry * Further updates * Various fixes (#604) * Various fixes * Address comments * Apply final feedback * Wording change * Add 'mission-critical' * Add EPUB * Implement comments * Implement comments * Final fix * Final fix * Update references to IBM Style with links, and remove marketing references (#609) * Mock-up of new link format to IBM Style with padlock icon * Remove marketing references and explain padlock icon in front matter * Update references to IBM Style with links * Implement suggestions part 1 * Implement suggestions part 2 * Update IaC (#612) * Updates for dashes, terminal, omitting output (#618) * Updates for dashes, terminal, omitting output * add shell prompt example * Further updates * Update abstract wording (#619) * Update abstract wording * Minor rewording * Add release notes (#620) * Add release notes * Apply feedback * Add 'hardened', update 'secure', update omitted output (#621) * Add 'hardened', update 'secure', update omitted output * Apply feedback * Updated audience section for Homepage (#623) * updating index page * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * updating index page for v7.0 (#624) * updating index page for the latest version * Update index.html Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> --------- Co-authored-by: julian-cable <79939933+julian-cable@users.noreply.github.com> * Add dark mode enhancement to What's New (#626) * Some maintenance updates for 7.1 (#635) * Some maintenance updates for 7.1 * Apply feedback and add release notes * A further round of maintenance updates for the 7.1 release (#641) * A further round of maintenance updates for the 7.1 release * Add dollar sign * Minor fix * Further fix * Jcable/allow object class (#643) * Update guidance for 'allow' * Add guidance for naming object classes * Implement feedback * Minor restructure and update release notes * Minor typing fix (#644) * Minor fixes for 'referring to' section * updating hompage version --------- 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: julian-cable <79939933+julian-cable@users.noreply.github.com> Co-authored-by: Julian Cable <jcable@redhat.com> Co-authored-by: Rachel Lee <131199744+rclee33@users.noreply.github.com> Co-authored-by: Alex Corcoles <alex@pdp7.net> Co-authored-by: Ashley D'Andrea <jdandrea@gmail.com> Co-authored-by: Steven Bonneville <sbonnevi@redhat.com> Co-authored-by: Rachel Lee <ralee@redhat.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.