Implement suggestions from Ashley D'Andrea #589
Merged
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
Jul 2, 2024
Closed
rclee33
reviewed
Jul 2, 2024
en-US/G.xml
Outdated
| <para> | ||
| IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". | ||
| If you are using IBM Style, use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". |
There was a problem hiding this comment.
Suggested change
| If you are using IBM Style, use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". | |
| If you are using IBM Style, then use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". |
en-US/Language.xml
Outdated
| @@ -527,7 +527,7 @@ | |||
| <term>low-hanging fruit</term> | |||
| <listitem> | |||
| <para> | |||
| Metaphor. Do not use. | |||
| Metaphor. Do not use. Instead, refer to what is meant, such as that the results are easily achieved. | |||
There was a problem hiding this comment.
I understand why we're providing an example here, but the suggestion to describe something as "easily achieved" contradicts the guidance to avoid describing something as easy. Consider replacing "easily" in this example.
Additionally, consider either adding a link to the entry on "Avoid stating something is easy", or add text similar to the following: "In general, avoid stating that a task is easy. Focus instead on how to perform the task, or how the outcome benefits the audience."
en-US/Language.xml
Outdated
| @@ -527,7 +527,7 @@ | |||
| <term>low-hanging fruit</term> | |||
| <listitem> | |||
| <para> | |||
| Metaphor. Do not use. | |||
| Metaphor. Do not use. Instead, refer to what is meant, such as that the results are easily achieved. | |||
There was a problem hiding this comment.
Suggested change
| Metaphor. Do not use. Instead, refer to what is meant, such as that the results are easily achieved. | |
| Metaphor. Do not use. Instead, describe the outcome or opportunity in more precise terms, such as "readily achievable goals" or "low-risk, high-yield opportunities". |
en-US/Translation.xml
Outdated
| @@ -42,7 +42,7 @@ | |||
| <para> | |||
| These appear as numbered lists. | |||
| Use this list type for multiple entries if you need to refer to one of the entries from elsewhere in your document, or where order is important. | |||
| For example, if you need to list the order of operations that are required to prepare for an installation, or list a sequence of events that occurs. | |||
| For example, use an ordered list if you need to list the order of operations that are required to prepare for an installation, or to list a sequence of events that occurs. | |||
There was a problem hiding this comment.
Suggested change
| For example, use an ordered list if you need to list the order of operations that are required to prepare for an installation, or to list a sequence of events that occurs. | |
| For example, use an ordered list for a sequence of steps to complete a task, or for a sequence of events. |
There was a problem hiding this comment.
I suggested an update to make the primary example more generic. I also updated the phrasing to avoid "use a list ... to list".
en-US/Language.xml
Outdated
| @@ -1168,7 +1168,7 @@ | |||
| </row> | |||
| <row> | |||
| <entry> Kubernetes is an open source system that makes it easy to manage containerized applications across multiple hosts. </entry> | |||
| <entry> Kubernetes is an open source system to manage containerized applications across multiple hosts. </entry> | |||
| <entry> Kubernetes is an open source system that is used to manage containerized applications across multiple hosts. </entry> | |||
There was a problem hiding this comment.
Suggested change
| <entry> Kubernetes is an open source system that is used to manage containerized applications across multiple hosts. </entry> | |
| <entry> Kubernetes is an open source system that manages containerized applications across multiple hosts. </entry> |
jdandrea
reviewed
Jul 3, 2024
en-US/G.xml
Outdated
| <para> | ||
| IBM style: Use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". | ||
| If you are using IBM Style, then use a non-breaking space between the value and the abbreviation. For example, "a 2 GB file". |
There was a problem hiding this comment.
I have an idea! Perhaps change this to "a 2&nbsp;GB file" so that the non-breaking space is made visible for illustrative purposes. If that makes sense, then I recommend the same for bpp.
I can file a separate issue for this if desired, since bpp is involved.
jdandrea
reviewed
Jul 3, 2024
en-US/U.xml
Outdated
| <listitem> | ||
| <para> | ||
| <emphasis>n.</emphasis> Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs. That is, use http://www.redhat.com and not www.redhat.com. | ||
| <emphasis>n.</emphasis> Include the appropriate protocol, such as http, ftp, or https, at the beginning of URLs or URIs. That is, use http://www.redhat.com and not www.redhat.com. |
There was a problem hiding this comment.
A minor nit; perhaps we can leave for another time:
In URI (and URL) parlance, that first component before the : is formally referred to as a scheme.
Schemes are semantically different from network protocols, yet they tend to have the same name! So the http or https scheme in a URL/URI is also the name of a protocol. Contrast this with thefile scheme, for example, which has no associated protocol. Also note that : and // are not part of the scheme either. Even those have names!
Still a minor nit for now. I can save for a separate issue if desired.
jdandrea
approved these changes
Jul 3, 2024
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.
This PR implements many suggestions from @jdandrea in this document:
https://docs.google.com/spreadsheets/d/1K3dlBNAb7Q6ZOSeCtKfxSDKfYWnYzWlbpups3P1JOMk