Skip to content

Implementing various feedback suggestions from Rachel #513

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
merged 3 commits into from
Aug 4, 2023
Merged

Implementing various feedback suggestions from Rachel #513

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
7336fd5
Implementing various feedback suggestions from Rachel
julian-cable Aug 4, 2023
9405171
Addressed review comments
julian-cable Aug 4, 2023
6011f96
Addressed further review comment
julian-cable Aug 4, 2023
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
8 changes: 4 additions & 4 deletions en-US/Cross_references.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,15 +40,15 @@

</section>
<section id="repeatability-test">
<title>The Repeatability Test</title>
<title>Repetition</title>
<para>
Must the information be repeated?
Repetition is a useful tool for reinforcing new knowledge and skills, emphasizing important ideas, and providing readers with important information at their point of need.
</para>
<para>
This is a hard question, and one that many authors abhor. Often the answer is yes. If the information is vital, and must appear in multiple places, then it must be repeated. In some circumstances, such is in online help, the reader wants the answer immediately. Do not force even one extra click on them. In a safety situation, it might be the only chance for the reader to find critical information quickly. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to.
Repeating necessary information also saves the reader time and effort. In some circumstances, such as when using online help, the reader is trying to answer an immediate question or to solve a problem. In a safety situation, it is important for the reader to find critical information quickly.
</para>
<para>
Cross-referencing is a good servant but a poor master. Content still rules!
If the information is vital, and must appear in multiple places, then it must be repeated. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to.
</para>

</section>
Expand Down
69 changes: 46 additions & 23 deletions en-US/Design.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -923,11 +923,11 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest

</section>
<section id="using-abbreviations">
<title>Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly</title>
<title>Abbreviations, Acronyms, Initialisms, and Special Characters</title>
<para>
This section describes how to use abbreviations, acronyms, and initialisms correctly in Red&nbsp;Hat documentation.
This section defines abbreviations, acronyms, initialisms, and special characters.
</para>
<formalpara>
<formalpara id="abbreviations">
<title>Abbreviations</title>
<para>
An abbreviation is a shortened form of a word or phrase. For example, <abbrev>Pty.</abbrev> and <abbrev>Inc.</abbrev> are abbreviations for "proprietary" and "incorporated", respectively. Read them as the word for which they are an abbreviation.
Expand All @@ -937,46 +937,68 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
<formalpara id="acronyms">
<title>Acronyms</title>
<para>
What are acronyms anyway?
They are similar to abbreviations and initialisms but they are pronounced as a word.
An acronym is a word that is formed from the initial letters of a name, such as ROM for <emphasis>R</emphasis>ead-<emphasis>O</emphasis>nly <emphasis>M</emphasis>emory, or by combining initial letters or part of a series of words, such as LILO for <emphasis>LI</emphasis>nux <emphasis>LO</emphasis>ader.
<acronym>COBOL</acronym> is the acronym for Common Business-oriented Language, and <acronym>POP</acronym> is the acronym for Post Office Protocol.
An acronym is a word that is formed from the initial letters of a name, such as ROM for <emphasis>R</emphasis>ead-<emphasis>O</emphasis>nly <emphasis>M</emphasis>emory, or by combining initial letters or part of a series of words, such as LILO for <emphasis>LI</emphasis>nux <emphasis>LO</emphasis>ader.
<acronym>COBOL</acronym> is the acronym for Common Business-oriented Language, and <acronym>POP</acronym> is the acronym for Post Office Protocol.
</para>

</formalpara>
<formalpara id="initialisms">
<title>Initialisms</title>
<para>
An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, FTP is an initialism for File Transfer Protocol.
</para>
</formalpara>

<formalpara id="special-chars">
<title>Special Characters</title>
<para>
For the purposes of this guide, special characters refer to those characters that are listed in <xref linkend="punc-names" />.
This section addresses how to use special characters as part of a file or directory name, such as "the <filename>.bashrc</filename> file" and "the <filename>_build/</filename> directory".
</para>
</formalpara>

<section id="abbreviations-correctly">
<title>Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly</title>
<para>
Consider pronunciation when using articles. For example, use "an <abbrev>RTS</abbrev> (real-time strategy)", because <abbrev>RTS</abbrev> is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a <acronym>RAM</acronym> upgrade", because <acronym>RAM</acronym> is an acronym and you pronounce it as a word (răm).
This section describes how to use abbreviations, acronyms, initialisms, and special characters correctly in Red&nbsp;Hat documentation.
</para>

<formalpara id="first-mentions">
<title>First Mentions</title>
<para>
Spell out most acronyms and initialisms before using them in text, such as "The Embedded DevKit (EDK) ...".
Unless the acronym or initialism stands for a proper noun, use sentence case for the spelled out version: for example, "central processing unit (CPU)".
Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML.
Unless required for the audience or the topic, do not spell out well-known abbreviations, such as HTML.
</para>
</formalpara>

<formalpara id="cap">
<title>Capitalization</title>
<para>
To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes.
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"); see the <citetitle>IBM Style Guide</citetitle> or another suitable reference if you are unsure.
</para>
</formalpara>

<formalpara id="articles">
<title>Articles</title>
<para>
Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the <citetitle>IBM Style Guide</citetitle> or another suitable reference if you are unsure.
When deciding which articles to use, consider pronunciation.
For example, use "an <abbrev>RTS</abbrev> (real-time strategy)", because <abbrev>RTS</abbrev> is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a <acronym>RAM</acronym> upgrade", because <acronym>RAM</acronym> is an acronym and you pronounce it as a word (răm).
</para>

<formalpara id="initialisms">
<title>Initialisms</title>
<para>
An initialism is an abbreviation that consists of the first letters of words in a phrase, syllables, or some combination thereof. Each character is pronounced separately. For example, <abbrev>FTP</abbrev> is an initialism for <systemitem class="protocol">File Transfer Protocol.</systemitem>
</para>

</formalpara>

<formalpara id="plurals">
<title>Plurals</title>
<para>
Consider pronunciation when using articles. See <xref linkend="acronyms" /> for more information.
To form the plural of an acronym, add a trailing, lowercase "s" or "es" without an apostrophe, for example, ROMs, PINs, BIOSes.
</para>
</formalpara>

<formalpara id="special-characters">
<title>Special Characters</title>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm having a little trouble understanding why special characters are addressed in the section on abbreviations, acronyms, and initialisms. That is, I see the connection around using pronunciation to determine article use, but special characters seem like a different category from the others. Along similar lines, this section provides guidance about using special characters, but they are not defined in the previous section along with the others. To address this gap, consider adding an entry defining "Special Characters" (in the context of naming?) in the previous section.

<para>
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
</para>
<para>
Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article.
</para>

</formalpara>
<para>
Expand All @@ -990,6 +1012,7 @@ STEP 14: COMMIT <emphasis>...output omitted...</emphasis> localhost/nexus:latest
<para>
Using "a <filename>-compile/</filename> directory" is correct, because you pronounce "a dash compile directory".
</para>
</section>

</section>
<section id="product-names">
Expand Down
70 changes: 35 additions & 35 deletions en-US/Language.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1092,13 +1092,16 @@
<title>Avoiding Ambiguities</title>
<variablelist>

<varlistentry id="proper-nouns">
<term> Capitalizing Proper Nouns </term>
<varlistentry id="homographs">
<term> Avoid May and Should </term>
<listitem>
<para>
In some cases it is not clear if a term refers to a concept or a proper noun or product name.
By using the correct capitalization, you help translators identify untranslatable proper nouns and Red&nbsp;Hat product names.
The verb "may" might indicate possibility or grant permission.
Similarly, "should" might imply a recommendation or express obligation or expectation.
A sentence containing one of these verbs often has a double meaning.
Avoid these types of words.
</para>

<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
Expand All @@ -1114,8 +1117,27 @@
</thead>
<tbody>
<row>
<entry> This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. </entry>
<entry> This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. </entry>
<entry> The <methodname>next()</methodname> method should return <code>null</code> to indicate the end of results. </entry>
<entry>
<para>
The <methodname>next()</methodname> method is expected to return <code>null</code> to indicate the end of results.
</para>
<para>
<emphasis>Or:</emphasis> The <methodname>next()</methodname> method must return <code>null</code> to indicate the end of results.
</para>
</entry>

</row>
<row>
<entry> It may be held in memory. </entry>
<entry>
<para>
It can be held in memory.
</para>
<para>
<emphasis>Or:</emphasis> It might be held in memory.
</para>
</entry>

</row>

Expand All @@ -1127,7 +1149,7 @@

</listitem>

</varlistentry>
</varlistentry>
<varlistentry id="easy">
<term> Avoid Stating that Something Is Easy </term>
<listitem>
Expand Down Expand Up @@ -1172,16 +1194,13 @@
</listitem>

</varlistentry>
<varlistentry id="homographs">
<term> Homographic Verbs </term>
<varlistentry id="proper-nouns">
<term> Capitalizing Proper Nouns </term>
<listitem>
<para>
The verb "may" might indicate possibility or grant permission.
Similarly, "should" might imply a recommendation or express obligation or expectation.
A sentence containing one of these verbs often has a double meaning.
Avoid these types of words.
In some cases it is not clear if a term refers to a concept or a proper noun or product name.
By using the correct capitalization, you help translators identify untranslatable proper nouns and Red&nbsp;Hat product names.
</para>

<table>
<title></title>
<tgroup cols="2" colsep="1" rowsep="1">
Expand All @@ -1197,27 +1216,8 @@
</thead>
<tbody>
<row>
<entry> The <methodname>next()</methodname> method should return <code>null</code> to indicate the end of results. </entry>
<entry>
<para>
The <methodname>next()</methodname> method is expected to return <code>null</code> to indicate the end of results.
</para>
<para>
<emphasis>Or:</emphasis> The <methodname>next()</methodname> method must return <code>null</code> to indicate the end of results.
</para>
</entry>

</row>
<row>
<entry> It may be held in memory. </entry>
<entry>
<para>
It can be held in memory.
</para>
<para>
<emphasis>Or:</emphasis> It might be held in memory.
</para>
</entry>
<entry> This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. </entry>
<entry> This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. </entry>

</row>

Expand Down