Skip to content

Merge all updates from dev to master for 6.0 release #447

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
daobrien merged 35 commits into from
Dec 13, 2022
Merged

Merge all updates from dev to master for 6.0 release #447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
9785670
Fixes extraneous comma.
Jul 19, 2022
e5916bb
Applied various fixes for 6.0
julian-cable Sep 1, 2022
ae16f44
Applied fixes from comments
julian-cable Oct 13, 2022
c2f2c1e
Fixes #409 and other required repairs.
Oct 14, 2022
49bd90a
Merge pull request #417 from StyleGuides/daobrien/409-remove-docbook-…
mweetman-redhat Oct 14, 2022
6c791f6
Fixes #416
Oct 14, 2022
eb051e5
Latest fixes
julian-cable Oct 14, 2022
c14d0b3
Merge branch 'dev' into daobrien/416-chris-wright-update
mweetman-redhat Oct 14, 2022
1ee5d51
Reapply update after merge conflict.
Oct 15, 2022
a614ab1
Merge pull request #418 from StyleGuides/daobrien/416-chris-wright-up…
daobrien Oct 15, 2022
2048498
Merge pull request #407 from StyleGuides/jcable/6.0-fixes
daobrien Oct 18, 2022
be533cf
Applied third batch of enhancements for 6.0 (#420)
julian-cable Oct 24, 2022
2298922
Applied second batch of enhancements for 6.0 (#419)
julian-cable Oct 25, 2022
a9b69e1
Applied first batch of enhancements for 6.0 (#414)
julian-cable Oct 25, 2022
f85ad53
Added audience, new in this release, fix for 'like' entry (#422)
julian-cable Nov 1, 2022
60d35a3
Revert addition of audience section
julian-cable Nov 2, 2022
80ec802
Merge pull request #423 from StyleGuides/jcable/audience-revert
daobrien Nov 2, 2022
9955b8a
Addresses #424 Add info on using captions.
Nov 4, 2022
c2fcf7a
Fixed a grammerior.
Nov 4, 2022
5e95632
Merge pull request #425 from StyleGuides/daobrien/424-update-captions
daobrien Nov 4, 2022
d123703
Added captions and callouts item to what's new (#428)
julian-cable Nov 7, 2022
d42d7f8
Fixes #356. Removes big RH logo from centre of page.
Nov 9, 2022
b5a84c8
Merge pull request #434 from StyleGuides/356-add-dark-mode-to-stylepe…
acomabon Nov 9, 2022
764cddc
Minor fix
julian-cable Nov 28, 2022
012828e
Added example for 'unset'
julian-cable Nov 28, 2022
b3f8e2b
Added updated wording about verbs in titles (#444)
julian-cable Nov 30, 2022
2ad9792
update preface.xml to add in audience file and resolve issue #408
Nov 30, 2022
6339235
Implement change from review
julian-cable Nov 30, 2022
cb94df1
Implement change from review
julian-cable Nov 30, 2022
b1d6567
Merge pull request #442 from StyleGuides/jcable/unset-438
nmuller66 Nov 30, 2022
3fca657
Merge pull request #440 from StyleGuides/jcable/439-fix
nmuller66 Nov 30, 2022
6704b3e
Merge pull request #445 from StyleGuides/nmuller-issue-408
nmuller66 Nov 30, 2022
917bd57
Final update to release notes for 6.0 (#446)
julian-cable Nov 30, 2022
794e842
Minor text tweaks.
Dec 12, 2022
aaf0b32
Apply fixes from Nicole and update release month (#449)
julian-cable Dec 12, 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
16 changes: 16 additions & 0 deletions en-US/Audience.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Conventions_for_Writers_and_Editors.ent">
%BOOK_ENTITIES;
]>
<section id="audience">
<title>Audience</title>
<para>
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.
</para>
<para>
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.
</para>

</section>

4 changes: 2 additions & 2 deletions en-US/Book_Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@
<section id="introductions">
<title>Introductions</title>
<para>
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.
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.
</para>

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

</formalpara>
Expand Down
8 changes: 1 addition & 7 deletions 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 All @@ -17,12 +17,6 @@

</abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
</imageobject>

</inlinemediaobject>

</corpauthor>
<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Expand Down
201 changes: 161 additions & 40 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
</formalpara>
<para>
Use title case also when referring to the titles of other publications, even if the title on the publication itself uses different casing.
</para>
</para>
<para>
The currently accepted reference for determining title case is at <ulink url="https://titlecase.com/titlecase">https://titlecase.com/titlecase</ulink>.
</para>
Expand All @@ -46,14 +46,15 @@
Do not use terminating periods.
</para>
</formalpara>
<!-- Commenting out this section following a change of advice.
<formalpara id="imperative-mood">
<title>Avoid Imperative Mood</title>
<formalpara id="verbs-titles">
<title>Verbs in Titles</title>
<para>
Use the gerund form (noun form of verb) for titles, not the imperative mood. For example, "Testing the Product", not "Test the Product".
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".
</para>

</formalpara>
<para>
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".
</para>
<para>
See the <citetitle>IBM Style Guide</citetitle> for more information.
</para>
Expand All @@ -62,7 +63,7 @@
Gerunds should be avoided elsewhere.
See <xref linkend="sentence-structure" />.
</para>
</important> -->
</important>
<formalpara>
<title>File Names, Commands, and Related Terms</title>
<para>
Expand All @@ -88,8 +89,8 @@
The following sections highlight exceptions or cases that might otherwise cause confusion.
</para>
<para>
When writing about items in a user interface (UI), match the capitalization and spelling of those items from the interface.
However, if the interface contains a spelling error, then correct the spelling in your writing, and get the interface corrected if possible.
When writing about items in a user interface (UI), match the capitalization and spelling of those items from the interface.
However, if the interface contains a spelling error, then correct the spelling in your writing, and get the interface corrected if possible.
Depending on the context, an option might be to write around an incorrectly spelled interface item rather than naming it specifically.
</para>
<section id="gui-elements-punctuation">
Expand Down Expand Up @@ -143,6 +144,37 @@

</section>
</section>
<section id="figures-illustrations">
<title>Figures, Illustrations, and Screen Captures</title>
<para>
Refer to the <citetitle>Figures</citetitle> section in the <citetitle>IBM Style Guide</citetitle> for general advice about using figures, illustrations, and screen captures.
</para>
<para>
The following specific conventions apply to using captions and callouts with figures in Red&nbsp;Hat technical documentation, and are generally recommended.
</para>
<itemizedlist>
<listitem>
<para>
If the image is well documented and described in the surrounding text, no caption or callouts are required.
</para>
</listitem>
<listitem>
<para>
If the image is not fully described in the surrounding text, use a caption or legend to complete the information for the reader.
</para>
</listitem>
<listitem>
<para>
If the image is complex and requires detailed explanation, consider using callouts to describe each of the relevant parts.
</para>
</listitem>
</itemizedlist>
<note>
<para>
Do not use callouts and captions on the same figure.
</para>
</note>
</section>
<section id="starting-apps">
<title>Starting Applications from the Desktop</title>
<para>
Expand Down Expand Up @@ -702,7 +734,7 @@ $ vi myFile.txt
<section id="refer-object-names">
<title>Referring to Object Names</title>
<para>
Do not use object names as part of normative grammar. A sentence should be complete without the object name.
When using object names, write a sentence so that it is complete without the object name.
</para>

<table>
Expand All @@ -721,7 +753,14 @@ $ vi myFile.txt
<tbody>
<row>
<entry> Find the current default <systemitem>StorageClass</systemitem>. </entry>
<entry> Either: Find the current default storage class. Or: Find the current default <systemitem>StorageClass</systemitem> value. </entry>
<entry>
<para>
Either: Find the current default storage class.
</para>
<para>
Or: Find the current default <systemitem>StorageClass</systemitem> value.
</para>
</entry>

</row>

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

</table>
<para>
Avoid starting or ending a sentence with an object name.
</para>

</section>
<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> <systemitem>Umount /mnt/save</systemitem>. </entry>
<entry> Unmount the <filename>/mnt/save</filename> directory. </entry>

</section>
</row>
<row>
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this <systemitem>nameserver</systemitem>. </entry>
<entry> Modify the <filename>/etc/resolv.conf</filename> file to use this name server. </entry>

</row>

</tbody>

</tgroup>

</table>
<para>
Place an object name before the noun that it modifies rather than after the noun.
</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> Enable the default module stream for the module <systemitem>python36</systemitem> and install all packages from that stream. </entry>
<entry> Enable the default module stream for the <systemitem>python36</systemitem> module and install all packages from that stream. </entry>

</row>

</tbody>

</tgroup>

</table>

</section>

</section>
<section id="document-currencies">
<title>Documenting Currencies</title>
<para>
Expand Down Expand Up @@ -800,21 +902,21 @@ $ vi myFile.txt
<formalpara id="special-characters">
<title>Special Characters</title>
<para>
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
</para>
</formalpara>
<para>
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
</para>

</formalpara>
<para>
If a file or directory name begins with a special character, such as an underscore, then you need to pronounce that character.
</para>

<para>
<para>
For example, using "an <filename>_build/</filename> directory" is correct, because you pronounce "an underscore build directory".
</para>
</para>

<para>
<para>
Using "a <filename>-compile/</filename> directory" is correct, because you pronounce "a dash compile directory".
</para>
</para>

</section>
<section id="product-names">
Expand All @@ -828,26 +930,26 @@ $ vi myFile.txt
</para>

</note>
<itemizedlist>
<listitem>
<!-- <itemizedlist>
<listitem> -->
<para>
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.
</para>

</listitem>
<listitem>
<!-- <listitem>
</listitem> -->
<para>
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.
</para>

</listitem>
<listitem>
<!-- <listitem>
</listitem> -->
<para>
Do not include "Inc." when referring to Red&nbsp;Hat except in legal documents.
</para>

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

</note>

</listitem>
<listitem>
<!-- <listitem>
</listitem> -->
<para>
Do not hyphenate or break a product name across lines, as in the following incorrect example:
Do not hyphenate or break a product name across lines.
</para>
<programlisting>
Open
-Shift
</programlisting>
</listitem>
</itemizedlist>
<example>
<title>Incorrect Example of Line Breaking</title>
<para>
<literallayout>
For advanced management capabilities with Red
Hat Satellite and cloud management services, use the Red
Hat Enterprise Linux Smart Management Add
-On.
</literallayout>
</para>
</example>
<!-- <listitem>
</itemizedlist> -->

</section>
<section id="nonbreaking-spaces">
Expand All @@ -889,6 +998,12 @@ $ vi myFile.txt
</para>

</listitem>
<listitem>
<para>
Between a numeral and a unit of measurement.
</para>

</listitem>

</itemizedlist>
<para>
Expand All @@ -907,13 +1022,19 @@ $ vi myFile.txt
</para>

</listitem>
<listitem>
<para>
The <systemitem>crashkernel=auto</systemitem> setting requires at least 1&#123;nbsp&#125;GB of memory.
</para>

</listitem>

</itemizedlist>

<para>
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.
</para>
<para>
<para>
Non-breaking spaces are not needed elsewhere in a product name and might cause undesirable line-breaking behavior.
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".
</para>
Expand Down
Loading