Skip to content

Commit 4fc1c91

Browse files
daobriendaobrien
authored
Merge pull request #447 from StyleGuides/dev
Merge all updates from dev to master for 6.0 release
2 parents 0088563 + aaf0b32 commit 4fc1c91

16 files changed

+1211
-106
lines changed

‎en-US/Audience.xml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?xml version='1.0' encoding='utf-8' ?>
2+
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3+
<!ENTITY % BOOK_ENTITIES SYSTEM "Conventions_for_Writers_and_Editors.ent">
4+
%BOOK_ENTITIES;
5+
]>
6+
<section id="audience">
7+
<title>Audience</title>
8+
<para>
9+
This guide is the official style guide for technical documentation for Red&nbsp;Hat training and certification content, including how to write for global audiences and translation, common mistakes to avoid, rules for everyday punctuation, and grammar.
10+
</para>
11+
<para>
12+
Other Red&nbsp;Hat technical documentation, including product documentation by Customer Content Services (CCS), follows the Red&nbsp;Hat supplementary style guide for product documentation at <ulink url="https://redhat-documentation.github.io/supplementary-style-guide/" /> instead of this Red&nbsp;Hat Technical Writing Style Guide.
13+
</para>
14+
15+
</section>
16+

‎en-US/Book_Design.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@
109109
<section id="introductions">
110110
<title>Introductions</title>
111111
<para>
112-
The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red&nbsp;Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to $productname" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product.
112+
The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red&nbsp;Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to &lt;product_name&gt;" near the beginning of the book to introduce the reader to the product. Do not use "Introduction" to introduce the book; that is the task of the Abstract. A further benefit of this usage is that the same introduction can be used across various books to introduce the same product.
113113
</para>
114114

115115
</section>
@@ -135,7 +135,7 @@
135135
<formalpara id="about">
136136
<title>About</title>
137137
<para>
138-
Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview".
138+
Do not use "about" or "about &lt;topic&gt;" as a title. The same reasoning applies here as to "overview".
139139
</para>
140140

141141
</formalpara>

‎en-US/Book_Info.xml

Lines changed: 1 addition & 7 deletions
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>
@@ -17,12 +17,6 @@
1717

1818
</abstract>
1919
<corpauthor>
20-
<inlinemediaobject>
21-
<imageobject>
22-
<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
23-
</imageobject>
24-
25-
</inlinemediaobject>
2620

2721
</corpauthor>
2822
<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

‎en-US/Design.xml

Lines changed: 161 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
</formalpara>
2222
<para>
2323
Use title case also when referring to the titles of other publications, even if the title on the publication itself uses different casing.
24-
</para>
24+
</para>
2525
<para>
2626
The currently accepted reference for determining title case is at <ulink url="https://titlecase.com/titlecase">https://titlecase.com/titlecase</ulink>.
2727
</para>
@@ -46,14 +46,15 @@
4646
Do not use terminating periods.
4747
</para>
4848
</formalpara>
49-
<!-- Commenting out this section following a change of advice.
50-
<formalpara id="imperative-mood">
51-
<title>Avoid Imperative Mood</title>
49+
<formalpara id="verbs-titles">
50+
<title>Verbs in Titles</title>
5251
<para>
53-
Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product".
52+
Usually, you start a title with the gerund form of a verb, which ends with "-ing", for example "Creating Branches". Choose a verb that refers to specific actions that users take, such as "Configuring", "Creating", "Installing", and "Merging".
5453
</para>
55-
5654
</formalpara>
55+
<para>
56+
The gerund verb form is not always required. For example, avoid verbs such as "Describing", "Introducing", and "Understanding", because they add little value. Instead, use a more specific verb or omit the verb. For example, instead of "Describing Initial Git Configuration", you can use "Initial Git Configuration".
57+
</para>
5758
<para>
5859
See the <citetitle>IBM Style Guide</citetitle> for more information.
5960
</para>
@@ -62,7 +63,7 @@
6263
Gerunds should be avoided elsewhere.
6364
See <xref linkend="sentence-structure" />.
6465
</para>
65-
</important> -->
66+
</important>
6667
<formalpara>
6768
<title>File Names, Commands, and Related Terms</title>
6869
<para>
@@ -88,8 +89,8 @@
8889
The following sections highlight exceptions or cases that might otherwise cause confusion.
8990
</para>
9091
<para>
91-
When writing about items in a user interface (UI), match the capitalization and spelling of those items from the interface.
92-
However, if the interface contains a spelling error, then correct the spelling in your writing, and get the interface corrected if possible.
92+
When writing about items in a user interface (UI), match the capitalization and spelling of those items from the interface.
93+
However, if the interface contains a spelling error, then correct the spelling in your writing, and get the interface corrected if possible.
9394
Depending on the context, an option might be to write around an incorrectly spelled interface item rather than naming it specifically.
9495
</para>
9596
<section id="gui-elements-punctuation">
@@ -143,6 +144,37 @@
143144

144145
</section>
145146
</section>
147+
<section id="figures-illustrations">
148+
<title>Figures, Illustrations, and Screen Captures</title>
149+
<para>
150+
Refer to the <citetitle>Figures</citetitle> section in the <citetitle>IBM Style Guide</citetitle> for general advice about using figures, illustrations, and screen captures.
151+
</para>
152+
<para>
153+
The following specific conventions apply to using captions and callouts with figures in Red&nbsp;Hat technical documentation, and are generally recommended.
154+
</para>
155+
<itemizedlist>
156+
<listitem>
157+
<para>
158+
If the image is well documented and described in the surrounding text, no caption or callouts are required.
159+
</para>
160+
</listitem>
161+
<listitem>
162+
<para>
163+
If the image is not fully described in the surrounding text, use a caption or legend to complete the information for the reader.
164+
</para>
165+
</listitem>
166+
<listitem>
167+
<para>
168+
If the image is complex and requires detailed explanation, consider using callouts to describe each of the relevant parts.
169+
</para>
170+
</listitem>
171+
</itemizedlist>
172+
<note>
173+
<para>
174+
Do not use callouts and captions on the same figure.
175+
</para>
176+
</note>
177+
</section>
146178
<section id="starting-apps">
147179
<title>Starting Applications from the Desktop</title>
148180
<para>
@@ -702,7 +734,7 @@ $ vi myFile.txt
702734
<section id="refer-object-names">
703735
<title>Referring to Object Names</title>
704736
<para>
705-
Do not use object names as part of normative grammar. A sentence should be complete without the object name.
737+
When using object names, write a sentence so that it is complete without the object name.
706738
</para>
707739

708740
<table>
@@ -721,7 +753,14 @@ $ vi myFile.txt
721753
<tbody>
722754
<row>
723755
<entry> Find the current default <systemitem>StorageClass</systemitem>. </entry>
724-
<entry> Either: Find the current default storage class. Or: Find the current default <systemitem>StorageClass</systemitem> value. </entry>
756+
<entry>
757+
<para>
758+
Either: Find the current default storage class.
759+
</para>
760+
<para>
761+
Or: Find the current default <systemitem>StorageClass</systemitem> value.
762+
</para>
763+
</entry>
725764

726765
</row>
727766

@@ -730,10 +769,73 @@ $ vi myFile.txt
730769
</tgroup>
731770

732771
</table>
772+
<para>
773+
Avoid starting or ending a sentence with an object name.
774+
</para>
733775

734-
</section>
776+
<table>
777+
<title></title>
778+
<tgroup cols="2" colsep="1" rowsep="1">
779+
<colspec colname="c1"></colspec>
780+
<colspec colname="c2"></colspec>
781+
<thead>
782+
<row>
783+
<entry> Example </entry>
784+
<entry> Improvement </entry>
785+
786+
</row>
787+
788+
</thead>
789+
<tbody>
790+
<row>
791+
<entry> <systemitem>Umount /mnt/save</systemitem>. </entry>
792+
<entry> Unmount the <filename>/mnt/save</filename> directory. </entry>
735793

736-
</section>
794+
</row>
795+
<row>
796+
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this <systemitem>nameserver</systemitem>. </entry>
797+
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this name server. </entry>
798+
799+
</row>
800+
801+
</tbody>
802+
803+
</tgroup>
804+
805+
</table>
806+
<para>
807+
Place an object name before the noun that it modifies rather than after the noun.
808+
</para>
809+
810+
<table>
811+
<title></title>
812+
<tgroup cols="2" colsep="1" rowsep="1">
813+
<colspec colname="c1"></colspec>
814+
<colspec colname="c2"></colspec>
815+
<thead>
816+
<row>
817+
<entry> Example </entry>
818+
<entry> Improvement </entry>
819+
820+
</row>
821+
822+
</thead>
823+
<tbody>
824+
<row>
825+
<entry> Enable the default module stream for the module <systemitem>python36</systemitem> and install all packages from that stream. </entry>
826+
<entry> Enable the default module stream for the <systemitem>python36</systemitem> module and install all packages from that stream. </entry>
827+
828+
</row>
829+
830+
</tbody>
831+
832+
</tgroup>
833+
834+
</table>
835+
836+
</section>
837+
838+
</section>
737839
<section id="document-currencies">
738840
<title>Documenting Currencies</title>
739841
<para>
@@ -800,21 +902,21 @@ $ vi myFile.txt
800902
<formalpara id="special-characters">
801903
<title>Special Characters</title>
802904
<para>
803-
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
804-
</para>
805-
806-
</formalpara>
807-
<para>
905+
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
906+
</para>
907+
908+
</formalpara>
909+
<para>
808910
If a file or directory name begins with a special character, such as an underscore, then you need to pronounce that character.
809911
</para>
810912

811-
<para>
913+
<para>
812914
For example, using "an <filename>_build/</filename> directory" is correct, because you pronounce "an underscore build directory".
813-
</para>
915+
</para>
814916

815-
<para>
917+
<para>
816918
Using "a <filename>-compile/</filename> directory" is correct, because you pronounce "a dash compile directory".
817-
</para>
919+
</para>
818920

819921
</section>
820922
<section id="product-names">
@@ -828,26 +930,26 @@ $ vi myFile.txt
828930
</para>
829931

830932
</note>
831-
<itemizedlist>
832-
<listitem>
933+
<!-- <itemizedlist>
934+
<listitem> -->
833935
<para>
834936
Restrictions apply to abbreviating Red&nbsp;Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red&nbsp;Hat OpenShift Container Platform, you can omit "Red&nbsp;Hat" after the first use.
835937
</para>
836938

837-
</listitem>
838-
<listitem>
939+
<!-- <listitem>
940+
</listitem> -->
839941
<para>
840942
Further restrictions apply to using acronyms and initialisms. In this same example, and only in technical documentation, "RHOCP" is acceptable after the first use of the full product name.
841943
</para>
842944

843-
</listitem>
844-
<listitem>
945+
<!-- <listitem>
946+
</listitem> -->
845947
<para>
846948
Do not include "Inc." when referring to Red&nbsp;Hat except in legal documents.
847949
</para>
848950

849-
</listitem>
850-
<listitem>
951+
<!-- <listitem>
952+
</listitem> -->
851953
<para>
852954
Do not use articles in front of product names. For example, do not write "the JBoss Enterprise&nbsp;Application&nbsp;Platform was ...".
853955
</para>
@@ -858,17 +960,24 @@ $ vi myFile.txt
858960

859961
</note>
860962

861-
</listitem>
862-
<listitem>
963+
<!-- <listitem>
964+
</listitem> -->
863965
<para>
864-
Do not hyphenate or break a product name across lines, as in the following incorrect example:
966+
Do not hyphenate or break a product name across lines.
865967
</para>
866-
<programlisting>
867-
Open
868-
-Shift
869-
</programlisting>
870-
</listitem>
871-
</itemizedlist>
968+
<example>
969+
<title>Incorrect Example of Line Breaking</title>
970+
<para>
971+
<literallayout>
972+
For advanced management capabilities with Red
973+
Hat Satellite and cloud management services, use the Red
974+
Hat Enterprise Linux Smart Management Add
975+
-On.
976+
</literallayout>
977+
</para>
978+
</example>
979+
<!-- <listitem>
980+
</itemizedlist> -->
872981

873982
</section>
874983
<section id="nonbreaking-spaces">
@@ -889,6 +998,12 @@ $ vi myFile.txt
889998
</para>
890999

8911000
</listitem>
1001+
<listitem>
1002+
<para>
1003+
Between a numeral and a unit of measurement.
1004+
</para>
1005+
1006+
</listitem>
8921007

8931008
</itemizedlist>
8941009
<para>
@@ -907,13 +1022,19 @@ $ vi myFile.txt
9071022
</para>
9081023

9091024
</listitem>
1025+
<listitem>
1026+
<para>
1027+
The <systemitem>crashkernel=auto</systemitem> setting requires at least 1&#123;nbsp&#125;GB of memory.
1028+
</para>
1029+
1030+
</listitem>
9101031

9111032
</itemizedlist>
9121033

9131034
<para>
9141035
If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red&nbsp;Hat" should never be broken over two lines.
9151036
</para>
916-
<para>
1037+
<para>
9171038
Non-breaking spaces are not needed elsewhere in a product name and might cause undesirable line-breaking behavior.
9181039
In particular, do not use non-breaking spaces between extended components of Red&nbsp;Hat product names. For example, "Red&nbsp;Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between any of the words after "Red&nbsp;Hat".
9191040
</para>

0 commit comments

Comments
 (0)