Skip to content

Applied various fixes for 6.0 #407

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 3 commits into from
Oct 18, 2022
Merged

Applied various fixes for 6.0 #407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e5916bb
Applied various fixes for 6.0
julian-cable Sep 1, 2022
ae16f44
Applied fixes from comments
julian-cable Oct 13, 2022
eb051e5
Latest fixes
julian-cable Oct 14, 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
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
41 changes: 24 additions & 17 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -828,26 +828,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 +858,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 Down
11 changes: 8 additions & 3 deletions en-US/Grammar.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
<section id="active-voice">
<title>Active Voice</title>
<para>
Use the active voice ("Type ... to start Linuxconf".) rather than passive ("Linuxconf can be started by typing ...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count.
Use the active voice ("Type ... to start Linuxconf") rather than passive ("Linuxconf can be started by typing ...") whenever possible. Active voice makes for more lively, interesting reading. It is more compelling than passive voice and helps to reduce word count.
</para>
<para>
This does not mean that the passive voice is forbidden. There are situations when using the passive voice is appropriate, such as release notes, technical notes, and similar material.
Expand Down Expand Up @@ -471,10 +471,15 @@
</thead>
<tbody>
<row>
<entry> The individual member of the social community often receives information via visual, symbolic channels. </entry>
<entry> People read. (Translation by Richard Feynman.) </entry>
<entry> The <command>fsck /dev/vdb1</command> command performs a file system check on the XFS file system residing on the <filename>/dev/vdb1</filename> partition. </entry>
<entry> The <command>fsck /dev/vdb1</command> command checks the XFS file system on the <filename>/dev/vdb1</filename> partition. </entry>

</row>
<row>
<entry> Red&nbsp;Hat Insights provides different services for the administration and monitoring of the registered systems that can be used for troubleshooting and even remediation of the issues identified. </entry>
<entry> Red&nbsp;Hat Insights services administer and monitor registered systems to troubleshoot and remediate issues. </entry>

</row>
<row>
<entry> Perform the installation of the product. </entry>
<entry> Install the product. </entry>
Expand Down
73 changes: 66 additions & 7 deletions en-US/Language.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,16 @@
</listitem>

</varlistentry>
<varlistentry>
<term>apples to apples</term>
<listitem>
<para>
Do not use. Explain instead what is meant, such as "a fair comparison".
</para>

</listitem>

</varlistentry>
<varlistentry>
<term>ask (as a noun), make the ask</term>
<listitem>
Expand All @@ -102,6 +111,16 @@

</listitem>

</varlistentry>
<varlistentry>
<term>at the end of the day</term>
<listitem>
<para>
Do not use. Explain what you mean, such as "considering all factors", or omit.
</para>

</listitem>

</varlistentry>
<varlistentry>
<term>at this point in time</term>
Expand Down Expand Up @@ -143,6 +162,16 @@
</listitem>

</varlistentry>
<!-- <varlistentry>
<term>boil the ocean</term>
<listitem>
<para>
Do not use. State exactly what you mean, such as "increase the scope hugely".
</para>

</listitem>

</varlistentry> -->
<varlistentry>
<term>bottom line</term>
<listitem>
Expand Down Expand Up @@ -196,30 +225,30 @@

</varlistentry>
<varlistentry>
<term>eat your own dogfood</term>
<term>data point</term>
<listitem>
<para>
Developer-speak. It means to use your own products. You can get a detailed description at <ulink url="http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food">http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food</ulink>.
Do not use.
</para>

</listitem>

</varlistentry>
<varlistentry>
<term>data point</term>
<term>dig deeper, delve deeper</term>
<listitem>
<para>
Do not use.
"Visit the following web link to dig deeper into [subject] ...". Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]."
</para>

</listitem>

</varlistentry>
<varlistentry>
<term>dig deeper, delve deeper</term>
<term>drop the ball</term>
<listitem>
<para>
"Visit the following web link to dig deeper into [subject] ...". Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]."
State instead exactly what you mean, such as "make a mistake".
</para>

</listitem>
Expand All @@ -234,6 +263,16 @@

</listitem>

</varlistentry>
<varlistentry>
<term>eat your own dogfood</term>
<listitem>
<para>
Developer-speak. It means to use your own products. You can get a detailed description at <ulink url="http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food">http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food</ulink>.
</para>

</listitem>

</varlistentry>
<varlistentry>
<term>enterprise-ready</term>
Expand Down Expand Up @@ -267,7 +306,17 @@

</varlistentry>
<varlistentry>
<term>flying by the seat of your pants</term>
<term>flog a dead horse</term>
<listitem>
<para>
Do not use. Explain exactly what you mean, such as "a waste of effort".
</para>

</listitem>

</varlistentry>
<varlistentry>
<term>fly by the seat of your pants</term>
<listitem>
<para>
Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context.
Expand Down Expand Up @@ -513,6 +562,16 @@

</listitem>

</varlistentry>
<varlistentry>
<term>on the same page</term>
<listitem>
<para>
Instead of "ensure that everyone is on the same page", use wording such as "ensure that everyone is aligned" or "ensure that everyone is in agreement".
</para>

</listitem>

</varlistentry>
<varlistentry>
<term>over the wire</term>
Expand Down
2 changes: 1 addition & 1 deletion en-US/Punctuation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -533,7 +533,7 @@ Deleted paragraph now that DocBook tagging no longer applies. -->
<example><title>Referring to Punctuation Marks</title>

<para>
Use a semicolon to separate two parts of a sentence that can each stand on their own.
Use a semicolon to separate two parts of a sentence that can each stand on its own.
</para>
<para>
The path contains the library qualifier in braces.
Expand Down
7 changes: 2 additions & 5 deletions en-US/Translation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,19 +71,16 @@
<para>
You can nest lists, but try to keep the number of levels to two or fewer.
To nest procedures in DocBook, use &lt;substep&gt; elements.
<!-- In AsciiDoc? -->
</para>
<section><title>Formatting Lists for Readability</title>
<para>
It is important to provide sufficient spacing between elements in your documents to facilitate reading and comprehension.
You can include a lot of information in a few short paragraphs but readers need to be able to process that information in chunks.
The same consideration applies to lists.
If you use DocBook to build itemized, ordered, or variable (definition) lists, you can use the <option>compact</option> or <option>normal</option> attributes to specify the spacing between list items.
DocBook uses the <option>normal</option> spacing attribute by default.
<!-- In AsciiDoc? -->
</para>
<para>
Use a list with normal spacing if any list item contains the following components:
In some authoring environments, you can choose between normal or compact spacing for lists.
Use a list with normal spacing if any list item contains the following components:
</para>
<itemizedlist>
<listitem>
Expand Down