Updated section about writing titles #492
Conversation
There was a problem hiding this comment.
My initial reaction to this is that it's very focused on our course designs and requirements. The Style Guide is broader than that. Note also that I would hesitate to update id's unless absolutely necessary. Whenever you update an id, any links to that section will break. The parts about omitting "Describing", etc., are fine; just remember the overall audience is not RHT, but rather anyone writing technical documentation.
|
I have reverted the ID of that title. |
It's not about "other" guidance, or widening the scope; in fact, quite the opposite. The way we're going atm we're reducing the scope, and focusing primarily on our course requirements, which is not what the RH Technical Writing Style Guide is about. Consider this: This is 100% about students taking a course. It might be useful if you're writing a subsection about procedures or similar, but in general it's too restrictive for my liking. Note also that there seem to be quite a few cases of smart quotes in this PR; where did they come from? We also need to be careful with our terminology. E.g., in "Configuring OpenShift" or whatever, "configuring" is not a gerund; it's a verb. Gerunds are nouns, or more specifically, a verb form which functions as a noun. It's often easier to just use examples of what works and what doesn't. |
|
If the purpose is go to add Pats changes then this looks good to me. But for future David's concerns are something we need to think about. |
|
tbh I disagree with merging this as-is, but I'm only one person. We need more eyes. |
|
I will review the wording one more time to see if I can suggest some changes to address your comments. But first I have some project PRs to attend to. |
|
I have made further edits. In an attempt to make the guidance more generic, I changed "student" to "user". For the one paragraph that is specific to training, I added an introductory statement to that effect. I have removed the smart quotes (which were probably from content that was pasted from a presentation). |
* 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>
@daobrien @sffrench Please review the "Writing Effective Titles" section, which I've updated to reflect the recently changed guidance that Pat announced.