Skip to content

Commit a9b69e1

Browse files
julian-cablejulian-cable
authored
Applied first batch of enhancements for 6.0 (#414)
* Adding snippet guidance Part 1 * Further enhancements to 6.0 * Fixes to implement feedback * Further fixes * Update to implement Fernando's feedback * Adding addressing of issue 399 to the scope * Implemented review comments
1 parent 2298922 commit a9b69e1

File tree

4 files changed

+476
-6
lines changed

4 files changed

+476
-6
lines changed

‎en-US/Book_Info.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<!-- Change title to "The Red Hat Style Guide" -->
99
<productname>Red&nbsp;Hat Technical Writing Style&nbsp;Guide</productname>
1010
<productnumber></productnumber>
11-
<edition>5.1</edition>
11+
<edition>6.0</edition>
1212
<pubsnumber>1</pubsnumber>
1313
<abstract>
1414
<para>

‎en-US/Grammar.xml

Lines changed: 317 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,44 @@
107107

108108
</section>
109109

110+
</section>
111+
<section id="countable-nouns">
112+
<title>Countable Nouns</title>
113+
<para>
114+
For nouns that are not countable, it is correct to use "less" and "amount", for example "less memory" or "the required amount of memory".
115+
For nouns that are countable, use "fewer" instead of "less", and use "number" instead of "amount".
116+
</para>
117+
<table>
118+
<title></title>
119+
<tgroup cols="2" colsep="1" rowsep="1">
120+
<colspec colname="c1"></colspec>
121+
<colspec colname="c2"></colspec>
122+
<thead>
123+
<row>
124+
<entry> Example </entry>
125+
<entry> Improvement </entry>
126+
127+
</row>
128+
129+
</thead>
130+
<tbody>
131+
<row>
132+
<entry> This passphrase configuration can improve security by providing less opportunities for someone else to see you type the passphrase. </entry>
133+
<entry> This passphrase configuration can improve security by providing fewer opportunities for someone else to see you type the passphrase. </entry>
134+
135+
</row>
136+
<row>
137+
<entry> Vim has fast, efficient keystrokes to delete an exact amount of words, lines, sentences, or paragraphs. </entry>
138+
<entry> Vim has fast, efficient keystrokes to delete an exact number of words, lines, sentences, or paragraphs. </entry>
139+
140+
</row>
141+
142+
</tbody>
143+
144+
</tgroup>
145+
146+
</table>
147+
110148
</section>
111149
<section id="using-who-whom">
112150
<title>Using Who, Whom, That, and Which Correctly</title>
@@ -428,11 +466,192 @@
428466

429467
</table>
430468

469+
<!-- Added section about avoiding causative verbs -->
470+
<formalpara id="causative">
471+
<title>Causative Verbs</title>
472+
<para>
473+
Avoid the construction "have something happen". Rewrite to replace "have" with a verb that describes the actual action.
474+
</para>
475+
476+
</formalpara>
477+
<table>
478+
<title></title>
479+
<tgroup cols="2" colsep="1" rowsep="1">
480+
<colspec colname="c1"></colspec>
481+
<colspec colname="c2"></colspec>
482+
<thead>
483+
<row>
484+
<entry> Example </entry>
485+
<entry> Improvement </entry>
486+
487+
</row>
488+
489+
</thead>
490+
<tbody>
491+
<row>
492+
<entry> The latter connection has no devices assigned. </entry>
493+
<entry> No devices are assigned to the latter connection. </entry>
494+
495+
</row>
496+
<row>
497+
<entry> To have the changes take effect … </entry>
498+
<entry> To apply the changes … </entry>
499+
500+
</row>
501+
502+
</tbody>
503+
504+
</tgroup>
505+
506+
</table>
507+
508+
<!-- <formalpara id="condition-action">
509+
<title>Condition and Action</title>
510+
<para>
511+
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.
512+
</para>
513+
514+
</formalpara>
515+
<table>
516+
<title></title>
517+
<tgroup cols="2" colsep="1" rowsep="1">
518+
<colspec colname="c1"></colspec>
519+
<colspec colname="c2"></colspec>
520+
<thead>
521+
<row>
522+
<entry> Example </entry>
523+
<entry> Improvement </entry>
524+
525+
</row>
526+
527+
</thead>
528+
<tbody>
529+
<row>
530+
<entry> Divide the storage devices into smaller chunks to create a partition. </entry>
531+
<entry> To create a partition, divide the storage devices into smaller chunks. </entry>
532+
533+
</row>
534+
535+
</tbody>
536+
537+
</tgroup>
538+
539+
</table> -->
540+
541+
<!-- Added section about "either, or" -->
542+
<formalpara id="either-or">
543+
<title>The Either-Or Construction</title>
544+
<para>
545+
Use the "either x ... or y" construction only to refer to a choice between two options, not for three or more options.
546+
</para>
547+
548+
</formalpara>
549+
<table>
550+
<title></title>
551+
<tgroup cols="2" colsep="1" rowsep="1">
552+
<colspec colname="c1"></colspec>
553+
<colspec colname="c2"></colspec>
554+
<thead>
555+
<row>
556+
<entry> Example </entry>
557+
<entry> Improvement </entry>
558+
559+
</row>
560+
561+
</thead>
562+
<tbody>
563+
<row>
564+
<entry> Scale up by adding more resources, with either more memory, CPUs, or disk space. </entry>
565+
<entry> Scale up by adding more resources, such as memory, CPUs, or disk space. </entry>
566+
567+
</row>
568+
569+
</tbody>
570+
571+
</tgroup>
572+
573+
</table>
574+
575+
<!-- Added section about "following" -->
576+
<formalpara id="following-noun">
577+
<title>Use of Following</title>
578+
<para>
579+
Use "following" with a noun.
580+
In a quiz question, "the following" is often superfluous.
581+
</para>
582+
583+
</formalpara>
584+
<table>
585+
<title></title>
586+
<tgroup cols="2" colsep="1" rowsep="1">
587+
<colspec colname="c1"></colspec>
588+
<colspec colname="c2"></colspec>
589+
<thead>
590+
<row>
591+
<entry> Example </entry>
592+
<entry> Improvement </entry>
593+
594+
</row>
595+
596+
</thead>
597+
<tbody>
598+
<row>
599+
<entry> Non-privileged users can use the role to configure the following: </entry>
600+
<entry> Non-privileged users can use the role to configure the following interfaces: </entry>
601+
602+
</row>
603+
<row>
604+
<entry> Which two of the following statements describe the benefits of Linux? </entry>
605+
<entry> Which two statements describe the benefits of Linux? </entry>
606+
607+
</row>
608+
609+
</tbody>
610+
611+
</tgroup>
612+
613+
</table>
614+
615+
<!-- Added section about "if, then" -->
616+
<formalpara id="if-then">
617+
<title>The If-Then Construction</title>
618+
<para>
619+
Generally, follow an "if" statement with a "then" statement.
620+
</para>
621+
622+
</formalpara>
623+
<table>
624+
<title></title>
625+
<tgroup cols="2" colsep="1" rowsep="1">
626+
<colspec colname="c1"></colspec>
627+
<colspec colname="c2"></colspec>
628+
<thead>
629+
<row>
630+
<entry> Example </entry>
631+
<entry> Improvement </entry>
632+
633+
</row>
634+
635+
</thead>
636+
<tbody>
637+
<row>
638+
<entry> If one service is started, the other is also started. </entry>
639+
<entry> If one service is started, then the other is also started. </entry>
640+
641+
</row>
642+
643+
</tbody>
644+
645+
</tgroup>
646+
647+
</table>
648+
431649
<!-- Added section about use of relative pronoun "that" -->
432650
<formalpara id="that">
433-
<title>"That" in Clauses</title>
651+
<title>Including That in Clauses</title>
434652
<para>
435-
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.
653+
Include the word "that" in clauses unless it results in writing that is too formal or stilted.
654+
Including the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English.
436655
</para>
437656

438657
</formalpara>
@@ -461,6 +680,54 @@
461680
</tgroup>
462681

463682
</table>
683+
684+
<!-- Added section about use of "this, that, these, those" -->
685+
<formalpara id="this-that-these-those">
686+
<title>Use of This That These Those</title>
687+
<para>
688+
Use "this", "that", "these", or "those" followed by a noun.
689+
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.
690+
</para>
691+
692+
</formalpara>
693+
<table>
694+
<title></title>
695+
<tgroup cols="2" colsep="1" rowsep="1">
696+
<colspec colname="c1"></colspec>
697+
<colspec colname="c2"></colspec>
698+
<thead>
699+
<row>
700+
<entry> Example </entry>
701+
<entry> Improvement </entry>
702+
703+
</row>
704+
705+
</thead>
706+
<tbody>
707+
<row>
708+
<entry> This causes SSH to lose the recorded identities of the remote systems. </entry>
709+
<entry>
710+
<para>
711+
Option 1: This action causes SSH to lose the recorded identities of the remote systems.
712+
</para>
713+
<para>
714+
Option 2: Consequently, SSH loses the recorded identities of the remote systems.
715+
</para>
716+
</entry>
717+
718+
</row>
719+
<row>
720+
<entry> A site can use these to self-allocate a private routable IP address space inside the organization. </entry>
721+
<entry> A site can use these unique local addresses to self-allocate a private routable IP address space inside the organization. </entry>
722+
723+
</row>
724+
725+
</tbody>
726+
727+
</tgroup>
728+
729+
</table>
730+
464731
<formalpara id="verbosity">
465732
<title> Verbosity </title>
466733
<para>
@@ -623,11 +890,56 @@ Split contractions and abbreviations into separate paragraphs. -->
623890
</formalpara>
624891

625892
</section>
626-
<section id="gender-references">
627-
<title>Gender References</title>
893+
<section id="pronouns-gender-references">
894+
<title>Pronouns and Gender References</title>
895+
<para>
896+
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.
897+
</para>
898+
<para>
899+
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.
900+
</para>
628901
<para>
629-
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.
902+
Avoid first person "I, we, our". Use second person "you" whenever possible.
630903
</para>
904+
<para>
905+
If referring to what Red&nbsp;Hat does, use "Red&nbsp;Hat" followed by a singular verb.
906+
</para>
907+
908+
<table>
909+
<title></title>
910+
<tgroup cols="2" colsep="1" rowsep="1">
911+
<colspec colname="c1"></colspec>
912+
<colspec colname="c2"></colspec>
913+
<thead>
914+
<row>
915+
<entry> Example </entry>
916+
<entry> Improvement </entry>
917+
918+
</row>
919+
920+
</thead>
921+
<tbody>
922+
<row>
923+
<entry> An engineer must be trained on the equipment that he services. </entry>
924+
<entry> Engineers must be trained on the equipment that they service. </entry>
925+
926+
</row>
927+
<row>
928+
<entry> In the web console, we can restart or shut down the system. </entry>
929+
<entry> In the web console, you can restart or shut down the system. </entry>
930+
931+
</row>
932+
<row>
933+
<entry> We recommend that you generate a service account for each microservice in your project. </entry>
934+
<entry> Red&nbsp;Hat recommends that you generate a service account for each microservice in your project. </entry>
935+
936+
</row>
937+
938+
</tbody>
939+
940+
</tgroup>
941+
942+
</table>
631943

632944
</section>
633945
<section id="tense">

0 commit comments

Comments
 (0)