Skip to content

Commit 5e95632

Browse files
daobriendaobrien
authored
Merge pull request #425 from StyleGuides/daobrien/424-update-captions
Addresses #424 Add info on using captions.
2 parents 80ec802 + c2fcf7a commit 5e95632

File tree

1 file changed

+71
-40
lines changed

1 file changed

+71
-40
lines changed

‎en-US/Design.xml

Lines changed: 71 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,7 +46,7 @@
4646
Do not use terminating periods.
4747
</para>
4848
</formalpara>
49-
<!-- Commenting out this section following a change of advice.
49+
<!-- Commenting out this section following a change of advice.
5050
<formalpara id="imperative-mood">
5151
<title>Avoid Imperative Mood</title>
5252
<para>
@@ -88,8 +88,8 @@
8888
The following sections highlight exceptions or cases that might otherwise cause confusion.
8989
</para>
9090
<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.
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.
9393
Depending on the context, an option might be to write around an incorrectly spelled interface item rather than naming it specifically.
9494
</para>
9595
<section id="gui-elements-punctuation">
@@ -143,6 +143,37 @@
143143

144144
</section>
145145
</section>
146+
<section id="figures-illustrations">
147+
<title>Figures, Illustrations, and Screen Captures</title>
148+
<para>
149+
Refer to the <citetitle>Figures</citetitle> section in the <citetitle>IBM Style Guide</citetitle> for general advice about using figures, illustrations, and screen captures.
150+
</para>
151+
<para>
152+
The following specific conventions apply to using captions and callouts with figures in Red&nbsp;Hat technical documentation, and are generally recommended.
153+
</para>
154+
<itemizedlist>
155+
<listitem>
156+
<para>
157+
If the image is well documented and described in the surrounding text, no caption or callouts are required.
158+
</para>
159+
</listitem>
160+
<listitem>
161+
<para>
162+
If the image is not fully described in the surrounding text, use a caption or legend to complete the information for the reader.
163+
</para>
164+
</listitem>
165+
<listitem>
166+
<para>
167+
If the image is complex and requires detailed explanation, consider using callouts to describe each of the relevant parts.
168+
</para>
169+
</listitem>
170+
</itemizedlist>
171+
<note>
172+
<para>
173+
Do not use callouts and captions on the same figure.
174+
</para>
175+
</note>
176+
</section>
146177
<section id="starting-apps">
147178
<title>Starting Applications from the Desktop</title>
148179
<para>
@@ -721,13 +752,13 @@ $ vi myFile.txt
721752
<tbody>
722753
<row>
723754
<entry> Find the current default <systemitem>StorageClass</systemitem>. </entry>
724-
<entry>
755+
<entry>
756+
<para>
757+
Either: Find the current default storage class.
758+
</para>
725759
<para>
726-
Either: Find the current default storage class.
760+
Or: Find the current default <systemitem>StorageClass</systemitem> value.
727761
</para>
728-
<para>
729-
Or: Find the current default <systemitem>StorageClass</systemitem> value.
730-
</para>
731762
</entry>
732763

733764
</row>
@@ -764,7 +795,7 @@ $ vi myFile.txt
764795
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this <systemitem>nameserver</systemitem>. </entry>
765796
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this name server. </entry>
766797

767-
</row>
798+
</row>
768799

769800
</tbody>
770801

@@ -801,9 +832,9 @@ $ vi myFile.txt
801832

802833
</table>
803834

804-
</section>
835+
</section>
805836

806-
</section>
837+
</section>
807838
<section id="document-currencies">
808839
<title>Documenting Currencies</title>
809840
<para>
@@ -870,21 +901,21 @@ $ vi myFile.txt
870901
<formalpara id="special-characters">
871902
<title>Special Characters</title>
872903
<para>
873-
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
874-
</para>
875-
876-
</formalpara>
877-
<para>
904+
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
905+
</para>
906+
907+
</formalpara>
908+
<para>
878909
If a file or directory name begins with a special character, such as an underscore, then you need to pronounce that character.
879910
</para>
880911

881-
<para>
912+
<para>
882913
For example, using "an <filename>_build/</filename> directory" is correct, because you pronounce "an underscore build directory".
883-
</para>
914+
</para>
884915

885-
<para>
916+
<para>
886917
Using "a <filename>-compile/</filename> directory" is correct, because you pronounce "a dash compile directory".
887-
</para>
918+
</para>
888919

889920
</section>
890921
<section id="product-names">
@@ -898,26 +929,26 @@ $ vi myFile.txt
898929
</para>
899930

900931
</note>
901-
<!-- <itemizedlist>
902-
<listitem> -->
932+
<!-- <itemizedlist>
933+
<listitem> -->
903934
<para>
904935
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.
905936
</para>
906937

907-
<!-- <listitem>
908-
</listitem> -->
938+
<!-- <listitem>
939+
</listitem> -->
909940
<para>
910941
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.
911942
</para>
912943

913-
<!-- <listitem>
914-
</listitem> -->
944+
<!-- <listitem>
945+
</listitem> -->
915946
<para>
916947
Do not include "Inc." when referring to Red&nbsp;Hat except in legal documents.
917948
</para>
918949

919-
<!-- <listitem>
920-
</listitem> -->
950+
<!-- <listitem>
951+
</listitem> -->
921952
<para>
922953
Do not use articles in front of product names. For example, do not write "the JBoss Enterprise&nbsp;Application&nbsp;Platform was ...".
923954
</para>
@@ -928,24 +959,24 @@ $ vi myFile.txt
928959

929960
</note>
930961

931-
<!-- <listitem>
932-
</listitem> -->
962+
<!-- <listitem>
963+
</listitem> -->
933964
<para>
934965
Do not hyphenate or break a product name across lines.
935966
</para>
936967
<example>
937968
<title>Incorrect Example of Line Breaking</title>
938-
<para>
969+
<para>
939970
<literallayout>
940-
For advanced management capabilities with Red
941-
Hat Satellite and cloud management services, use the Red
942-
Hat Enterprise Linux Smart Management Add
971+
For advanced management capabilities with Red
972+
Hat Satellite and cloud management services, use the Red
973+
Hat Enterprise Linux Smart Management Add
943974
-On.
944-
</literallayout>
945-
</para>
975+
</literallayout>
976+
</para>
946977
</example>
947-
<!-- <listitem>
948-
</itemizedlist> -->
978+
<!-- <listitem>
979+
</itemizedlist> -->
949980

950981
</section>
951982
<section id="nonbreaking-spaces">
@@ -1002,7 +1033,7 @@ $ vi myFile.txt
10021033
<para>
10031034
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.
10041035
</para>
1005-
<para>
1036+
<para>
10061037
Non-breaking spaces are not needed elsewhere in a product name and might cause undesirable line-breaking behavior.
10071038
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".
10081039
</para>

0 commit comments

Comments
 (0)