diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index 5468451..aba9f6b 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -40,15 +40,15 @@
- The Repeatability Test + Repetition - 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. - 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. - 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.
diff --git a/en-US/Design.xml b/en-US/Design.xml index 3d4684c..ceb68ec 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -923,11 +923,11 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
- Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly + Abbreviations, Acronyms, Initialisms, and Special Characters - This section describes how to use abbreviations, acronyms, and initialisms correctly in Red Hat documentation. + This section defines abbreviations, acronyms, initialisms, and special characters. - + Abbreviations An abbreviation is a shortened form of a word or phrase. For example, Pty. and Inc. are abbreviations for "proprietary" and "incorporated", respectively. Read them as the word for which they are an abbreviation. @@ -937,46 +937,68 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Acronyms - 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 Read-Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. - COBOL is the acronym for Common Business-oriented Language, and POP 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 Read-Only Memory, or by combining initial letters or part of a series of words, such as LILO for LInux LOader. + COBOL is the acronym for Common Business-oriented Language, and POP is the acronym for Post Office Protocol. + + + + + Initialisms + + 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. + + Special Characters + + For the purposes of this guide, special characters refer to those characters that are listed in . + This section addresses how to use special characters as part of a file or directory name, such as "the .bashrc file" and "the _build/ directory". + + + +
+ Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly - Consider pronunciation when using articles. For example, use "an RTS (real-time strategy)", because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade", because RAM 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 Hat documentation. + + First Mentions 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. + + + Capitalization - 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 IBM Style Guide or another suitable reference if you are unsure. + + + Articles - Be sure to use correct capitalization for acronyms. Not all acronyms are capitalized (for example, "spool"); see the IBM Style Guide or another suitable reference if you are unsure. + When deciding which articles to use, consider pronunciation. + For example, use "an RTS (real-time strategy)", because RTS is an initialism and you pronounce the first character as an "R" (är). Conversely, use "a RAM upgrade", because RAM is an acronym and you pronounce it as a word (răm). - - - Initialisms - - 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. - - + + + Plurals - Consider pronunciation when using articles. See 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. + + Special Characters - - Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article. - + + Consider pronunciation when referring to file or directory names that begin with special characters, and use the correct indefinite article. + @@ -990,6 +1012,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest Using "a -compile/ directory" is correct, because you pronounce "a dash compile directory". +
diff --git a/en-US/Language.xml b/en-US/Language.xml index c7fc7c1..6370179 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1092,13 +1092,16 @@ Avoiding Ambiguities - - Capitalizing Proper Nouns + + Avoid May and Should - 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 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. + @@ -1114,8 +1117,27 @@ - This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. - This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode. + The next() method should return null to indicate the end of results. + + + The next() method is expected to return null to indicate the end of results. + + + Or: The next() method must return null to indicate the end of results. + + + + + + It may be held in memory. + + + It can be held in memory. + + + Or: It might be held in memory. + + @@ -1127,7 +1149,7 @@ - + Avoid Stating that Something Is Easy @@ -1172,16 +1194,13 @@ - - Homographic Verbs + + Capitalizing Proper Nouns - 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 Hat product names. -
@@ -1197,27 +1216,8 @@ - The next() method should return null to indicate the end of results. - - - The next() method is expected to return null to indicate the end of results. - - - Or: The next() method must return null to indicate the end of results. - - - - - - It may be held in memory. - - - It can be held in memory. - - - Or: It might be held in memory. - - + This property must be enabled when you are using CTDB in a Windows domain or in active directory security mode. + This property must be enabled when you are using CTDB in a Windows domain or in Active Directory security mode.