Skip to content

Update references to IBM Style with links, and remove marketing references #609

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 5 commits into from
Sep 13, 2024
Merged

Update references to IBM Style with links, and remove marketing references #609

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
846302d
Mock-up of new link format to IBM Style with padlock icon
julian-cable Sep 4, 2024
71b3b85
Remove marketing references and explain padlock icon in front matter
julian-cable Sep 4, 2024
3950ab8
Update references to IBM Style with links
julian-cable Sep 4, 2024
a56b158
Implement suggestions part 1
julian-cable Sep 12, 2024
07d73ae
Implement suggestions part 2
julian-cable Sep 13, 2024
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
11 changes: 6 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
WritingStyleGuide
=================

A guide to writing clear, concise, and consistent technical documentation.
This guide is the official style guide for Red Hat training and certification content, and for all other technical documentation except as stated.
Red Hat product documentation by Customer Content Services (CCS) follows the Red Hat supplementary style guide at https://redhat-documentation.github.io/supplementary-style-guide/ instead of this Red Hat Technical Writing Style Guide.

The Red Hat Style Guide and Word Usage Dictionary is a joint effort by various groups within Red Hat.
The Red Hat Technical Writing Style Guide includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary.

It covers recommended design practices, how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and sources of information for the less common cases.
This guide is a public guide. It is reviewed and maintained by Red Hat. Contributions from the wider community are always welcomed.

It is based on The IBM Style Guide but differs in several key areas, uses the Merriam-Webster Unabridged Dictionary and American Heritage Dictionary as spelling references, and the Chicago Manual of Style (17th Ed.) for further grammatical and style decisions.
Other resources for technical writing are listed in the "Resources" section of the guide.

Dependencies:

```
$ sudo dnf install publican
```

Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that.
Also, follow the instructions at https://github.com/RedHatTraining/redhat-styleguide-xsl (access for Red Hat only) to build `publican-brand-redhat-*.noarch.rpm` and install that.

To build:

Expand Down
14 changes: 14 additions & 0 deletions en-US/Audience.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,20 @@
</para>
<para>
Other resources for technical writing are listed in <xref linkend="resources"/>.
Of these resources,
<ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>
is available for Red&nbsp;Hat employees to access online, but does not have a wider circulation.
Links in this guide to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink> are denoted by a padlock icon
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</section>
Expand Down
19 changes: 15 additions & 4 deletions en-US/B.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@
<term>big data</term>
<listitem>
<para>
<emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red&nbsp;Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, per AP style, even when used as a complex adjective.
<emphasis>n., adj.</emphasis> Always use lowercase. Do not capitalize except at the beginning of a sentence, or if it is part of a Red&nbsp;Hat product, service, solution, or business unit name. Refer also to <xref linkend="cloud" />. Big data is also never hyphenated, even when used as a compound modifier.
</para>

</listitem>
Expand Down Expand Up @@ -227,7 +227,13 @@
Correct. Named after George Boole, who first developed the concept.
</para>
<para>
According to the <citetitle>IBM Style Guide</citetitle>, it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type.
According to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>,
it is acceptable to use "boolean" (lowercase) in API programming information when it refers to a primitive return type.
</para>
<para>
To set Boolean values in YAML files, use <varname>true</varname> or <varname>false</varname>, written lowercase, rather than <varname>yes</varname> or <varname>no</varname>, because YAML&nbsp;1.2 and later versions do not support the latter syntax.
Expand Down Expand Up @@ -312,10 +318,15 @@

</varlistentry>
<varlistentry id="breadcrumb-trail">
<term>breadcrumb trail</term>
<term>breadcrumb, breadcrumb trail</term>
<listitem>
<para>
Refer to the <citetitle>IBM Style Guide</citetitle> for initial guidance on how to use this term.
For initial guidance on how to use this term, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>
<note>
<para>
Expand Down
31 changes: 26 additions & 5 deletions en-US/C.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,12 @@
When referring to a compact disk, use "CD". For example, "Insert the CD into the CD drive". The plural is "CDs".
</para>
<para>
Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for more information.
For more information, refer to the Word Usage section of <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</listitem>
Expand Down Expand Up @@ -159,7 +164,12 @@
</para>
<!-- Added comment about "click on". -->
<para>
Refer to the Word Usage chapter of the <citetitle>IBM Style Guide</citetitle> for more information.
For more information, refer to the Word Usage section of <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</listitem>
Expand Down Expand Up @@ -250,10 +260,16 @@

</varlistentry>
<varlistentry id="combo-box">
<term>combo-box</term>
<term>combo box</term>
<listitem>
<para>
Do not use as an abbreviation for "combination box". Refer to the relevant entry in the <citetitle>IBM Style Guide</citetitle> for further usage information.
Do not use as an abbreviation for "combination box".
For further usage information, refer to the relevant entry in <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</listitem>
Expand Down Expand Up @@ -319,7 +335,12 @@
<term>command line, command prompt, command-line</term>
<listitem>
<para>
Refer to the appropriate entries in the <citetitle>IBM Style Guide</citetitle> for an explanation of how to use these terms.
For an explanation of how to use these terms, refer to the appropriate entries in <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</listitem>
Expand Down
24 changes: 18 additions & 6 deletions en-US/D.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,19 @@
<term>dash</term>
<listitem>
<para>
In technical publications, the <citetitle>IBM Style Guide</citetitle> recommends not to use em&nbsp;dashes or en&nbsp;dashes at all. Use a colon or other suitable punctuation.
In technical publications, <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon> recommends not to use em&nbsp;dashes. Use a colon or other suitable punctuation.
En&nbsp;dashes are used to show a range.
Refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=punctuation-dashes"><citetitle>Dashes</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</listitem>
Expand All @@ -35,13 +47,13 @@
<para>
<emphasis>n.</emphasis> Use the two-word form unless referring to a product name or other proper noun where the one-word form is used.
</para>
<warning>
<!-- <warning>
<title>Marketing Publications Exception</title>
<para>
In marketing publications, use the one-word form of this term unless referring to a product name or other proper noun where the two-word form is used.
</para>

</warning>
</warning> -->

</listitem>

Expand All @@ -62,13 +74,13 @@
<para>
<emphasis>n.</emphasis> Use the two-word form.
</para>
<warning>
<!-- <warning>
<title>Marketing Publications Exception</title>
<para>
In marketing publications, the one-word form is recommended.
</para>

</warning>
</warning> -->

</listitem>

Expand Down Expand Up @@ -230,7 +242,7 @@
<term>disk, disc</term>
<listitem>
<para>
Use "compact disc" or "hard disk". Refer to the <citetitle>IBM Style Guide</citetitle> for more information and example use cases.
Use "compact disc" or "hard disk".
</para>
<!-- Removed reference to "diskette". -->

Expand Down
52 changes: 38 additions & 14 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@
Use sentence case for figure captions, legends, diagram labels, and table column headers.
They are not classified as titles.
</para>
<warning>
<!-- <warning>
<title>Marketing and Brand Capitalization Guide</title>
<para>
The Red&nbsp;Hat Marketing and Brand groups and some other groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title.
</para>

</warning>
</warning> -->

<formalpara>
<title>Punctuation</title>
Expand Down Expand Up @@ -102,9 +102,6 @@
</table>
<para>
In training content, avoid using a verb such as "Discussing" or "Demonstrating" in objectives for students. Such verbs might refer instead to what the instructor or the course content covers, or to a student group activity in class.
</para>
<para>
Refer to the <citetitle>IBM Style Guide</citetitle> for more information.
</para>
<important>
<para>
Expand Down Expand Up @@ -159,7 +156,12 @@
<section id="documenting-ui">
<title>Documenting the User Interface</title>
<para>
In all cases, refer to the <citetitle>IBM Style Guide</citetitle> for initial guidance.
For initial guidance in all cases, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=elements-ui"><citetitle>UI Elements</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
The following sections highlight exceptions or cases that might otherwise cause confusion.
</para>
<para>
Expand Down Expand Up @@ -201,7 +203,12 @@
</para>
</example>
<para>
Refer to the <citetitle>UI elements</citetitle> chapter in the <citetitle>IBM Style Guide</citetitle> for more information.
For more information, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=elements-ui"><citetitle>UI Elements</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>
<section>
<title>Moving Through Multiple UI Options</title>
Expand All @@ -217,7 +224,12 @@
<section id="figures-illustrations">
<title>Figures, Illustrations, and Screenshots</title>
<para>
Refer to the <citetitle>Figures</citetitle> section in the <citetitle>IBM Style Guide</citetitle> for general advice about using figures, illustrations, and screenshots.
For general advice about using figures, illustrations, and screenshots, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=format-figures"><citetitle>Figures</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>
<para>
The following specific conventions apply to using captions and callouts with figures in Red&nbsp;Hat technical documentation, and are generally recommended.
Expand Down Expand Up @@ -288,7 +300,12 @@
</para>
</blockquote>
<para>
Refer to <command>info bash</command> and the <citetitle>IBM Style Guide</citetitle> for further guidance.
For further guidance, refer to <command>info bash</command>, and to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=technical-elements"><citetitle>Technical Elements</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>
<para>
The following examples are intended to highlight correct usage.
Expand Down Expand Up @@ -766,10 +783,7 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
<formalpara id="choosing-realistic-names">
<title>Choosing a Realistic Name</title>
<para>
Consider the following points when choosing a realistic name: <footnote> <para>
Examples taken from the <citetitle>IBM Style Guide</citetitle> and the <citetitle>Google Developer Documentation Style Guide</citetitle>.
</para>
</footnote>
Consider the following points when choosing a realistic name:
</para>

</formalpara>
Expand Down Expand Up @@ -802,6 +816,10 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
However, for the name "Brian Strong", a corresponding email address of <email>bstrong@example.com</email> might not work so well (when read out, it sounds like "be strong").
Consider also any implications for names in different languages.
</para>
<para>
Refer also to the
<ulink url="https://developers.google.com/style"><citetitle>Google Developer Documentation Style Guide</citetitle></ulink>.
</para>

</listitem>

Expand Down Expand Up @@ -1052,7 +1070,13 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
<title>Capitalization</title>
<para>
Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)".
Not all acronyms are capitalized (for example, "spool"); refer to the <citetitle>IBM Style Guide</citetitle> or another suitable reference if you are unsure.
Not all acronyms are capitalized (for example, "spool"); refer to
<ulink url="https://www.ibm.com/docs/en/ibm-style?topic=grammar-capitalization"><citetitle>Capitalization</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon> or to another suitable reference if you are unsure.
</para>
</formalpara>

Expand Down
15 changes: 13 additions & 2 deletions en-US/F.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,12 @@
<term>file extensions (general usage)</term>
<listitem>
<para>
Refer to <citetitle>File names, file types, and directory names</citetitle> in the <citetitle>IBM Style Guide</citetitle>.
Refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=elements-files-directories"><citetitle>Files and Directories</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</listitem>
Expand All @@ -104,7 +109,13 @@
<term>file mode, file name, file system, file type</term>
<listitem>
<para>
<emphasis>n.</emphasis> Write as shown, two words, unless used as a variable. Refer to the <citetitle>IBM Style Guide</citetitle> for more information.
<emphasis>n.</emphasis> Write as shown, two words, unless used as a variable.
For more information, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>
<para>
<emphasis>adj.</emphasis> Hyphenate when used as a compound adjective. For example, "file-system attributes".
Expand Down
2 changes: 1 addition & 1 deletion en-US/G.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
<listitem>
<para>
Abbreviation of gigabyte.
<!-- Depending on the type of content you are writing, refer either to <citetitle>The AP Style Guide</citetitle> or the <citetitle>IBM Style Guide.</citetitle> -->
<!-- Depending on the type of content you are writing, refer either to <citetitle>The AP Style Guide</citetitle> or <citetitle>IBM Style.</citetitle> -->
</para>
<!-- <para>
AP style: Do not use a space between the value and the abbreviation. For example, "a 2GB file".
Expand Down
7 changes: 6 additions & 1 deletion en-US/Grammar.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -958,7 +958,12 @@ Split contractions and abbreviations into separate paragraphs. -->
No hard and fast rules exist for hyphenation.
In general, do not hyphenate unless required for clarity, or your other references declare that hyphens are required.
The following is general guidance; if you are unsure about whether to hyphenate, ask your peers.
Refer also to the "Hyphens" topic in the <citetitle>IBM Style Guide</citetitle>.
Refer to <ulink url="https://www.ibm.com/docs/en/ibm-style?topic=punctuation-hyphens"><citetitle>Hyphens</citetitle></ulink> in <citetitle>IBM Style</citetitle>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

<formalpara id="hyphenate-for-clarity">
Expand Down
7 changes: 6 additions & 1 deletion en-US/H.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,12 @@
<para>
<emphasis>n.</emphasis> Usually one word.
Capitalize the "H" at the beginning of a sentence.
Refer to the <citetitle>IBM Style Guide</citetitle> for more information.
For more information, refer to <ulink url="https://www.ibm.com/docs/en/ibm-style"><citetitle>IBM Style</citetitle></ulink>
<guiicon><inlinemediaobject>
<imageobject>
<imagedata fileref="images/padlock.png"/>
</imageobject>
</inlinemediaobject></guiicon>.
</para>

</listitem>
Expand Down
Loading