Skip to content

Applied first batch of enhancements for 6.0 #414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julian-cable merged 9 commits into from
Oct 25, 2022
Merged

Applied first batch of enhancements for 6.0 #414

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c59529a
Adding snippet guidance Part 1
julian-cable Sep 29, 2022
5cf40ab
Further enhancements to 6.0
julian-cable Oct 6, 2022
8c58dca
Fixes to implement feedback
julian-cable Oct 14, 2022
0932667
Further fixes
julian-cable Oct 14, 2022
0b99211
Update to implement Fernando's feedback
julian-cable Oct 17, 2022
4d14415
Adding addressing of issue 399 to the scope
julian-cable Oct 20, 2022
e3f6120
Merge branch 'dev' into jcable/6.0-enhancements
julian-cable Oct 25, 2022
7c25c0e
Implemented review comments
julian-cable Oct 25, 2022
4f0f09c
Resolve conflicts
julian-cable Oct 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion en-US/Book_Info.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<!-- Change title to "The Red Hat Style Guide" -->
<productname>Red&nbsp;Hat Technical Writing Style&nbsp;Guide</productname>
<productnumber></productnumber>
<edition>5.1</edition>
<edition>6.0</edition>
<pubsnumber>1</pubsnumber>
<abstract>
<para>
Expand Down
322 changes: 317 additions & 5 deletions en-US/Grammar.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,44 @@

</section>

</section>
<section id="countable-nouns">
<title>Countable Nouns</title>
<para>
For nouns that are not countable, it is correct to use "less" and "amount", for example "less memory" or "the required amount of memory".
For nouns that are countable, use "fewer" instead of "less", and use "number" instead of "amount".
</para>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> This passphrase configuration can improve security by providing less opportunities for someone else to see you type the passphrase. </entry>
<entry> This passphrase configuration can improve security by providing fewer opportunities for someone else to see you type the passphrase. </entry>

</row>
<row>
<entry> Vim has fast, efficient keystrokes to delete an exact amount of words, lines, sentences, or paragraphs. </entry>
<entry> Vim has fast, efficient keystrokes to delete an exact number of words, lines, sentences, or paragraphs. </entry>

</row>

</tbody>

</tgroup>

</table>

</section>
<section id="using-who-whom">
<title>Using Who, Whom, That, and Which Correctly</title>
Expand Down Expand Up @@ -428,11 +466,192 @@

</table>

<!-- Added section about avoiding causative verbs -->
<formalpara id="causative">
<title>Causative Verbs</title>
<para>
Avoid the construction "have something happen". Rewrite to replace "have" with a verb that describes the actual action.
</para>

</formalpara>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> The latter connection has no devices assigned. </entry>
<entry> No devices are assigned to the latter connection. </entry>

</row>
<row>
<entry> To have the changes take effect … </entry>
<entry> To apply the changes … </entry>

</row>

</tbody>

</tgroup>

</table>

<!-- <formalpara id="condition-action">
<title>Condition and Action</title>
<para>
A condition should precede an action. A clause that explains "why", or for what purpose, should come before a statement of what the action is or how it is done.
</para>

</formalpara>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> Divide the storage devices into smaller chunks to create a partition. </entry>
<entry> To create a partition, divide the storage devices into smaller chunks. </entry>
Comment on lines +530 to +531
Copy link
Collaborator

@daobrien daobrien Oct 10, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not really an example of a condition. Conditions typically start with "if": "If X then Y." This example is reversing "Do X to achieve Y" to become "To achieve Y, do X."

I also think we need a better example. "Dividing storage devices into smaller chunks" could mean a variety of things, and not necessarily create partitions. Maybe have a look at https://docs.fedoraproject.org/en-US/quick-docs/creating-a-disk-partition-in-linux/
I think it'd be pretty easy to make up a "bad example" and then improve it using the commands and examples documented here.

Copy link
Collaborator Author

@julian-cable julian-cable Oct 14, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My intent here was something other than an "if ... then" construction. I've removed the entry for now, and will think further about what to do.


</row>

</tbody>

</tgroup>

</table> -->

<!-- Added section about "either, or" -->
<formalpara id="either-or">
<title>The Either-Or Construction</title>
<para>
Use the "either x ... or y" construction only to refer to a choice between two options, not for three or more options.
</para>

</formalpara>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> Scale up by adding more resources, with either more memory, CPUs, or disk space. </entry>
<entry> Scale up by adding more resources, such as memory, CPUs, or disk space. </entry>

</row>

</tbody>

</tgroup>

</table>

<!-- Added section about "following" -->
<formalpara id="following-noun">
<title>Use of Following</title>
<para>
Use "following" with a noun.
In a quiz question, "the following" is often superfluous.
</para>

</formalpara>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> Non-privileged users can use the role to configure the following: </entry>
<entry> Non-privileged users can use the role to configure the following interfaces: </entry>

</row>
<row>
<entry> Which two of the following statements describe the benefits of Linux? </entry>
<entry> Which two statements describe the benefits of Linux? </entry>

</row>

</tbody>

</tgroup>

</table>

<!-- Added section about "if, then" -->
<formalpara id="if-then">
<title>The If-Then Construction</title>
<para>
Generally, follow an "if" statement with a "then" statement.
</para>

</formalpara>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> If one service is started, the other is also started. </entry>
<entry> If one service is started, then the other is also started. </entry>

</row>

</tbody>

</tgroup>

</table>

<!-- Added section about use of relative pronoun "that" -->
<formalpara id="that">
<title>"That" in Clauses</title>
<title>Including That in Clauses</title>
<para>
Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English.
Include the word "that" in clauses unless it results in writing that is too formal or stilted.
Including the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English.
</para>

</formalpara>
Expand Down Expand Up @@ -461,6 +680,54 @@
</tgroup>

</table>

<!-- Added section about use of "this, that, these, those" -->
<formalpara id="this-that-these-those">
<title>Use of This That These Those</title>
<para>
Use "this", "that", "these", or "those" followed by a noun.
Doing so improves clarity for readers whose primary language is not English, and improves accuracy of translation into other languages where these words differ based on the gender of the noun that they refer to.
</para>

</formalpara>
<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> This causes SSH to lose the recorded identities of the remote systems. </entry>
<entry>
<para>
Option 1: This action causes SSH to lose the recorded identities of the remote systems.
</para>
<para>
Option 2: Consequently, SSH loses the recorded identities of the remote systems.
</para>
</entry>

</row>
<row>
<entry> A site can use these to self-allocate a private routable IP address space inside the organization. </entry>
<entry> A site can use these unique local addresses to self-allocate a private routable IP address space inside the organization. </entry>

</row>

</tbody>

</tgroup>

</table>

<formalpara id="verbosity">
<title> Verbosity </title>
<para>
Expand Down Expand Up @@ -623,11 +890,56 @@ Split contractions and abbreviations into separate paragraphs. -->
</formalpara>

</section>
<section id="gender-references">
<title>Gender References</title>
<section id="pronouns-gender-references">
<title>Pronouns and Gender References</title>
<para>
Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is easier to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb.
</para>
<para>
In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "users" or "new users". Do not use "one" in place of "you" when writing technical documentation, because it is too formal. Do not use "it" to refer to a person.
</para>
<para>
Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person.
Avoid first person "I, we, our". Use second person "you" whenever possible.
</para>
<para>
If referring to what Red&nbsp;Hat does, use "Red&nbsp;Hat" followed by a singular verb.
</para>

<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
<colspec colname="c1"></colspec>
<colspec colname="c2"></colspec>
<thead>
<row>
<entry> Example </entry>
<entry> Improvement </entry>

</row>

</thead>
<tbody>
<row>
<entry> An engineer must be trained on the equipment that he services. </entry>
<entry> Engineers must be trained on the equipment that they service. </entry>

</row>
<row>
<entry> In the web console, we can restart or shut down the system. </entry>
<entry> In the web console, you can restart or shut down the system. </entry>

</row>
<row>
<entry> We recommend that you generate a service account for each microservice in your project. </entry>
<entry> Red&nbsp;Hat recommends that you generate a service account for each microservice in your project. </entry>

</row>

</tbody>

</tgroup>

</table>

</section>
<section id="tense">
Expand Down
Loading