Skip to content

Added audience, new in this release, fix for 'like' entry #422

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 2 commits into from
Nov 1, 2022
Merged

Added audience, new in this release, fix for 'like' entry #422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6d06ea
Added audience, new in this release, fix for 'like' entry
julian-cable Oct 31, 2022
04e9b13
Minor fixes
julian-cable Nov 1, 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>

2 changes: 1 addition & 1 deletion en-US/L.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@

</varlistentry>
<varlistentry id="like">
<term>lifecycle</term>
<term>like</term>
<listitem>
<para>
Avoid "like" to mean "such as".
Expand Down
99 changes: 99 additions & 0 deletions en-US/New.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,105 @@
]>
<section id="new">
<title>New in This Release</title>
<formalpara id="new_60">
<title>Release 6.0</title>
<para>Major update in October 2022 to add further style and grammar guidance:</para>
</formalpara>
<itemizedlist>
<listitem>
<para>Added audience information for this guide.</para>
</listitem>
<listitem>
<para>Avoid redundant words.</para>
</listitem>
<listitem>
<para>Avoid a causative verb.</para>
</listitem>
<listitem>
<para>Words to use with countable nouns.</para>
</listitem>
<listitem>
<para>Use of "either-or" construction.</para>
</listitem>
<listitem>
<para>Avoid stating that something is easy to do or to use.</para>
</listitem>
<listitem>
<para>Avoid first person.</para>
</listitem>
<listitem>
<para>Use "following" with a noun.</para>
</listitem>
<listitem>
<para>Avoid hyphenating with an "-ly" prefix: added an example.</para>
</listitem>
<listitem>
<para>If-Then statements.</para>
</listitem>
<listitem>
<para>Make a full lead-in sentence to introduce a list.</para>
</listitem>
<listitem>
<para>Making list items parallel.</para>
</listitem>
<listitem>
<para>Updated guidance about use of compact lists.</para>
</listitem>
<listitem>
<para>Using noun strings.</para>
</listitem>
<listitem>
<para>Avoid a noun followed by an "-ing" word.</para>
</listitem>
<listitem>
<para>Using object names.</para>
</listitem>
<listitem>
<para>Placement of "only".</para>
</listitem>
<listitem>
<para>Preposition at the end of a sentence.</para>
</listitem>
<listitem>
<para>Use straight rather than curly quotation marks.</para>
</listitem>
<listitem>
<para>Avoid "(s)" for plural.</para>
</listitem>
<listitem>
<para>Added further examples of slang, idioms, and metaphors to avoid.</para>
</listitem>
<listitem>
<para>Avoid a slash.</para>
</listitem>
<listitem>
<para>Spacing with a unit of measurement.</para>
</listitem>
<listitem>
<para>Improved succinctness examples.</para>
</listitem>
<listitem>
<para>Avoid "there is", "there are".</para>
</listitem>
<listitem>
<para>Use "this", "that", "these", "those" with a noun.</para>
</listitem>
<listitem>
<para>Replaced use of "$" as a variable marker in this guide to use angle brackets instead.</para>
</listitem>
<listitem>
<para>Use of "whether" versus "if".</para>
</listitem>
<listitem>
<para>New or updated usage entries: like, once, while.</para>
</listitem>
<listitem>
<para>Various other fixes.</para>
</listitem>

</itemizedlist>


<formalpara id="new_51">
<title>Release 5.1</title>
<para>Minor update in January 2022 to address some reported issues:</para>
Expand Down
3 changes: 3 additions & 0 deletions en-US/Preface.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
]>
<preface id="pref-preface">
<title>Preface</title>
<xi:include href="Audience.xml" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="Common_Content/Audience.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</xi:fallback>
</xi:include>
<xi:include href="New.xml" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="Common_Content/New.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</xi:fallback>
</xi:include>
Expand Down