diff --git a/en-US/Audience.xml b/en-US/Audience.xml new file mode 100644 index 0000000..165da34 --- /dev/null +++ b/en-US/Audience.xml @@ -0,0 +1,16 @@ + + +%BOOK_ENTITIES; +]> +
+ Audience + + This guide is the official style guide for technical documentation for Red Hat training and certification content, including how to write for global audiences and translation, common mistakes to avoid, rules for everyday punctuation, and grammar. + + + Other Red Hat technical documentation, including product documentation by Customer Content Services (CCS), follows the Red Hat supplementary style guide for product documentation at instead of this Red Hat Technical Writing Style Guide. + + +
+ diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index b49b797..636518f 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -109,7 +109,7 @@
Introductions - The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory (TM) tools, that Red 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 Hat technical documentation does not use this term on its own. Instead, use the phrase "Introduction to <product_name>" 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.
@@ -135,7 +135,7 @@ About - Do not use "about" or "about $topic" as a title. The same reasoning applies here as to "overview". + Do not use "about" or "about <topic>" as a title. The same reasoning applies here as to "overview". diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml index 2d513ce..163cbb2 100644 --- a/en-US/Book_Info.xml +++ b/en-US/Book_Info.xml @@ -8,7 +8,7 @@ Red Hat Technical Writing Style Guide - 5.1 + 6.0 1 @@ -17,12 +17,6 @@ - - - - - - diff --git a/en-US/Design.xml b/en-US/Design.xml index ab20c74..297d79f 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -21,7 +21,7 @@ Use title case also when referring to the titles of other publications, even if the title on the publication itself uses different casing. - + The currently accepted reference for determining title case is at https://titlecase.com/titlecase. @@ -46,14 +46,15 @@ Do not use terminating periods. - + File Names, Commands, and Related Terms @@ -88,8 +89,8 @@ The following sections highlight exceptions or cases that might otherwise cause confusion. - When writing about items in a user interface (UI), match the capitalization and spelling of those items from the interface. - However, if the interface contains a spelling error, then correct the spelling in your writing, and get the interface corrected if possible. + When writing about items in a user interface (UI), match the capitalization and spelling of those items from the interface. + However, if the interface contains a spelling error, then correct the spelling in your writing, and get the interface corrected if possible. Depending on the context, an option might be to write around an incorrectly spelled interface item rather than naming it specifically.
@@ -143,6 +144,37 @@
+
+ Figures, Illustrations, and Screen Captures + + Refer to the Figures section in the IBM Style Guide for general advice about using figures, illustrations, and screen captures. + + + The following specific conventions apply to using captions and callouts with figures in Red Hat technical documentation, and are generally recommended. + + + + + If the image is well documented and described in the surrounding text, no caption or callouts are required. + + + + + If the image is not fully described in the surrounding text, use a caption or legend to complete the information for the reader. + + + + + If the image is complex and requires detailed explanation, consider using callouts to describe each of the relevant parts. + + + + + + Do not use callouts and captions on the same figure. + + +
Starting Applications from the Desktop @@ -702,7 +734,7 @@ $ vi myFile.txt
Referring to Object Names - Do not use object names as part of normative grammar. A sentence should be complete without the object name. + When using object names, write a sentence so that it is complete without the object name. @@ -721,7 +753,14 @@ $ vi myFile.txt Find the current default StorageClass. - Either: Find the current default storage class. Or: Find the current default StorageClass value. + + + Either: Find the current default storage class. + + + Or: Find the current default StorageClass value. + + @@ -730,10 +769,73 @@ $ vi myFile.txt
+ + Avoid starting or ending a sentence with an object name. + -
+ + + + + + + + Example + Improvement + + + + + + + Umount /mnt/save. + Unmount the /mnt/save directory. - + + + Modify the /etc/resolv.conf file to use this nameserver. + Modify the /etc/resolv.conf file to use this name server. + + + + + + + +
+ + Place an object name before the noun that it modifies rather than after the noun. + + + + + + + + + + Example + Improvement + + + + + + + Enable the default module stream for the module python36 and install all packages from that stream. + Enable the default module stream for the python36 module and install all packages from that stream. + + + + + + + +
+ +
+ +
Documenting Currencies @@ -800,21 +902,21 @@ $ vi myFile.txt 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. + + + + If a file or directory name begins with a special character, such as an underscore, then you need to pronounce that character. - + For example, using "an _build/ directory" is correct, because you pronounce "an underscore build directory". - + - + Using "a -compile/ directory" is correct, because you pronounce "a dash compile directory". - +
@@ -828,26 +930,26 @@ $ vi myFile.txt - - + Restrictions apply to abbreviating Red Hat product or solution names in public-facing documents. Always use the full name on first use. For some products, for example Red Hat OpenShift Container Platform, you can omit "Red Hat" after the first use. - - + 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. - - + Do not include "Inc." when referring to Red Hat except in legal documents. - - + Do not use articles in front of product names. For example, do not write "the JBoss Enterprise Application Platform was ...". @@ -858,17 +960,24 @@ $ vi myFile.txt - - + - 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. - - Open - -Shift - - - + + Incorrect Example of Line Breaking + + + For advanced management capabilities with Red + Hat Satellite and cloud management services, use the Red + Hat Enterprise Linux Smart Management Add + -On. + + + +
@@ -889,6 +998,12 @@ $ vi myFile.txt + + + Between a numeral and a unit of measurement. + + + @@ -907,13 +1022,19 @@ $ vi myFile.txt + + + The crashkernel=auto setting requires at least 1{nbsp}GB of memory. + + + If you are working with images or other objects where space is especially tight, this rule is more flexible, but "Red Hat" should never be broken over two lines. - + Non-breaking spaces are not needed elsewhere in a product name and might cause undesirable line-breaking behavior. In particular, do not use non-breaking spaces between extended components of Red Hat product names. For example, "Red Hat Enterprise Linux OpenStack Platform" does not require a non-breaking space between any of the words after "Red Hat". diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 1a65572..2eb37eb 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -11,7 +11,7 @@
Active Voice - 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. 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. @@ -107,6 +107,44 @@
+
+
+ Countable Nouns + + For nouns that are not countable, it is correct to use "less" and "amount", for example "less memory" or "the required amount of memory". + For nouns that are countable, use "fewer" instead of "less", and use "number" instead of "amount". + + + + + + + + + Example + Improvement + + + + + + + This passphrase configuration can improve security by providing less opportunities for someone else to see you type the passphrase. + This passphrase configuration can improve security by providing fewer opportunities for someone else to see you type the passphrase. + + + + Vim has fast, efficient keystrokes to delete an exact amount of words, lines, sentences, or paragraphs. + Vim has fast, efficient keystrokes to delete an exact number of words, lines, sentences, or paragraphs. + + + + + + + +
+
Using Who, Whom, That, and Which Correctly @@ -252,7 +290,7 @@
Sentence Structure - A sentence is one, complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). + A sentence is one complete thought. A sentence expresses something about a subject (a person, place, or thing) and a verb (what the subject is or does). Consider the following points when constructing sentences: @@ -268,6 +306,18 @@ The Start button, which you can find in the bottom left corner of your screen (also activated by the "Windows key" on your keyboard, the one between the Ctrl and Alt keys), provides a central starting point for applications and tasks, and can be customized according to your individual preferences so that it presents menu items relevant to you instead of presenting the standard items that come with the default installation of the operating system, items which, in my opinion, are irrelevant for most users these days who really only need access to an internet browser such as Google Chrome or Mozilla Firefox. + + + Preposition at the End of a Sentence + + Allow a preposition at the end of a sentence to avoid otherwise awkward wording. + + + + + For example, instead of "Click the workspace to which you want to switch", which can sound stilted, it flows better to use "Click the workspace to switch to". + + Run-on Sentences @@ -416,11 +466,192 @@ + + + Causative Verbs + + Avoid the construction "have something happen". Rewrite to replace "have" with a verb that describes the actual action. + + + + + + + + + + + Example + Improvement + + + + + + + The latter connection has no devices assigned. + No devices are assigned to the latter connection. + + + + To have the changes take effect … + To apply the changes … + + + + + + + +
+ + + + + + The Either-Or Construction + + Use the "either x ... or y" construction only to refer to a choice between two options, not for three or more options. + + + + + + + + + + + Example + Improvement + + + + + + + Scale up by adding more resources, with either more memory, CPUs, or disk space. + Scale up by adding more resources, such as memory, CPUs, or disk space. + + + + + + + +
+ + + + Use of Following + + Use "following" with a noun. + In a quiz question, "the following" is often superfluous. + + + + + + + + + + + Example + Improvement + + + + + + + Non-privileged users can use the role to configure the following: + Non-privileged users can use the role to configure the following interfaces: + + + + Which two of the following statements describe the benefits of Linux? + Which two statements describe the benefits of Linux? + + + + + + + +
+ + + + The If-Then Construction + + Generally, follow an "if" statement with a "then" statement. + + + + + + + + + + + Example + Improvement + + + + + + + If one service is started, the other is also started. + If one service is started, then the other is also started. + + + + + + + +
+ - "That" in Clauses + Including That in Clauses - Include the word "that" in clauses unless it results in writing that is too formal or stilted. The use of the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. + Include the word "that" in clauses unless it results in writing that is too formal or stilted. + Including the conjunction "that" makes the sentence easier to translate and improves clarity for readers whose primary language is not English. @@ -449,6 +680,54 @@ + + + + Use of This That These Those + + Use "this", "that", "these", or "those" followed by a noun. + Doing so improves clarity for readers whose primary language is not English, and improves accuracy of translation into other languages where these words differ based on the gender of the noun that they refer to. + + + + + + + + + + + Example + Improvement + + + + + + + This causes SSH to lose the recorded identities of the remote systems. + + + Option 1: This action causes SSH to lose the recorded identities of the remote systems. + + + Option 2: Consequently, SSH loses the recorded identities of the remote systems. + + + + + + A site can use these to self-allocate a private routable IP address space inside the organization. + A site can use these unique local addresses to self-allocate a private routable IP address space inside the organization. + + + + + + + +
+ Verbosity @@ -471,10 +750,15 @@ - The individual member of the social community often receives information via visual, symbolic channels. - People read. (Translation by Richard Feynman.) + The fsck /dev/vdb1 command performs a file system check on the XFS file system residing on the /dev/vdb1 partition. + The fsck /dev/vdb1 command checks the XFS file system on the /dev/vdb1 partition. + + Red 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. + Red Hat Insights services administer and monitor registered systems to troubleshoot and remediate issues. + + Perform the installation of the product. Install the product. @@ -573,7 +857,7 @@ Split contractions and abbreviations into separate paragraphs. --> Do not hyphenate "open source", even when used as a complex adjective. - Do not hyphenate a compound that includes an adverb ending in -ly, whether it comes before or after the noun. This is described in Chicago Manual of Style 7.82. + Do not hyphenate a compound that includes an adverb that ends in -ly, whether it comes before or after the noun, because it is never ambiguous. This is described in Chicago Manual of Style 7.82. For example, "Red Hat Enterprise Linux is a production-ready, commercially supported Linux distribution." @@ -606,11 +890,56 @@ Split contractions and abbreviations into separate paragraphs. -->
-
- Gender References +
+ Pronouns and Gender References + + Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is easier to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb. + + + In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "users" or "new users". Do not use "one" in place of "you" when writing technical documentation, because it is too formal. Do not use "it" to refer to a person. + - Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb. In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. + Avoid first person "I, we, our". Use second person "you" whenever possible. + + If referring to what Red Hat does, use "Red Hat" followed by a singular verb. + + + + + + + + + + Example + Improvement + + + + + + + An engineer must be trained on the equipment that he services. + Engineers must be trained on the equipment that they service. + + + + In the web console, we can restart or shut down the system. + In the web console, you can restart or shut down the system. + + + + We recommend that you generate a service account for each microservice in your project. + Red Hat recommends that you generate a service account for each microservice in your project. + + + + + + + +
diff --git a/en-US/L.xml b/en-US/L.xml index bbd920b..07c969b 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -104,6 +104,17 @@ + + like + + + Avoid "like" to mean "such as". + For example, instead of "Namespaces can include resources like network interfaces", use "Namespaces can include resources such as network interfaces". + + + + + Linux diff --git a/en-US/Language.xml b/en-US/Language.xml index e75460f..e9d6273 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -90,7 +90,16 @@ + + apples to apples + + + Do not use. Explain instead what is meant, such as "a fair comparison". + + + + ask (as a noun), make the ask @@ -102,6 +111,16 @@ + + + at the end of the day + + + Do not use. Explain what you mean, such as "considering all factors", or omit. + + + + at this point in time @@ -143,6 +162,16 @@ + bottom line @@ -196,30 +225,30 @@ - eat your own dogfood + data point - Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + Do not use. - data point + dig deeper, delve deeper - 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]." - dig deeper, delve deeper + drop the ball - "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". @@ -234,6 +263,16 @@ + + + eat your own dogfood + + + Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + + + + enterprise-ready @@ -267,7 +306,17 @@ - flying by the seat of your pants + flog a dead horse + + + Do not use. Explain exactly what you mean, such as "a waste of effort". + + + + + + + fly by the seat of your pants Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context. @@ -513,6 +562,16 @@ + + + on the same page + + + 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". + + + + over the wire @@ -907,15 +966,10 @@
-
Inclusive Language - In a blog post, Red Hat senior vice president and chief technology officer, Chris Wright, affirms a commitment for Red Hat to identify and replace problematic language that is potentially divisive and does not foster inclusion: + Chris Wright, Red Hat Chief Technology Officer and Senior Vice President, Global Engineering, affirms in a blog post a commitment for Red Hat to identify and replace problematic language that is potentially divisive and does not foster inclusion: @@ -946,6 +1000,54 @@ Numbers (move from N entry) -->
+ +
+ Avoiding Redundant Words + + Avoid redundant words, such as "actually", "really", "simply" and "very". They are typically filler words that add no value to a sentence. + + + Redundant words might also occur where two words or phrases are used that mean approximately the same thing, such as "revert back" versus "revert", or that add nothing to the sentence, such as "located on" versus "on". + + + + + + + + + + Example + Improvement + + + + + + + Remote users can connect to network resources simply by authenticating to their local machine. + Remote users can connect to network resources by authenticating to their local machine. + + + + Any settings that are changed with this command revert back to their original settings when the daemon restarts. + Any settings that are changed with this command revert to their original settings when the daemon restarts. + + + + Restore the LUKS2 header to the encrypted volume located on the `/dev/sda1` partition. + Restore the LUKS2 header to the encrypted volume on the `/dev/sda1` partition. + + + + + + + +
+ +
+
Avoiding Ambiguities @@ -986,6 +1088,49 @@ Numbers (move from N entry) --> + + + Avoid Stating that Something Is Easy + + + Avoid stating that a task is easy to do or that a product is easy to use. Avoid "friendly" and "user-friendly" and similar terms. Focus instead on how to accomplish a task or on relevant features of a product. + + + + + + + + + Example + Improvement + + + + + + + Mounting a device is relatively simple. + Identify the device for mounting, ensure that the mount point exists, and mount the device on the mount point. + (Omit the first sentence.) + To mount a device, identify the device for mounting, ensure that the mount point exists, and mount the device on the mount point. + + + + Kubernetes is an open source system that makes it easy to manage containerized applications across multiple hosts. + Kubernetes is an open source system to manage containerized applications across multiple hosts. + + + + + + + +
+ + + + Homographic Verbs @@ -1009,12 +1154,26 @@ Numbers (move from N entry) --> 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. + + + 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. + + + It can be held in memory. + + + Or: It might be held in memory. + + @@ -1053,8 +1212,15 @@ Numbers (move from N entry) --> - To create another administrator, click New on the File menu. - To create another administrator account, click New on the File menu. OR To set privileges for another administrator, click New on the File menu. + To create another administrator, click File > New. + + + To create another administrator account, click File > New. + + + Or: To set privileges for another administrator, click File > New. + + @@ -1097,7 +1263,14 @@ Numbers (move from N entry) --> Use the utility to run activities and save your settings. - Depending on the meaning: Use the utility to run activities and to save your settings (if the utility does both functions). Or: Use the utility to run activities, and then when you are done, save your settings (if the process consists of two separate steps, of which the utility does only one). + Depending on the meaning: + + Use the utility to run activities and to save your settings (if the utility does both functions). + + + Or: Use the utility to run activities, and then save your settings (if the process consists of two separate steps, of which the utility does only one). + + @@ -1146,6 +1319,55 @@ Numbers (move from N entry) --> + + Misplaced Only + + + Ensure that "only" is placed directly before the word that it modifies, which often should not be a verb. + + + + + + + + + Example + Improvement + + + + + + + + + Users can only delete files that they own. + + + (Misleadingly suggests that users cannot take any actions other than deletion on those files) + + + + + Users can delete only files that they own. + + + (Clarifies the files that deletion applies to) + + + + + + + + + +
+ + + + Pronouns @@ -1194,6 +1416,47 @@ Numbers (move from N entry) --> + + + Use of "There Is" and "There Are" + + + Avoid "there is", "there are", and "there might be", because the subject of the sentence is unclear. + + + + + + + + + + Example + Improvement + + + + + + + The initial error message suggests there is a failure when opening a file. + The initial error message suggests a failure when opening a file. + + + + There are multiple static inventory formats supported by Ansible. + Ansible supports multiple static inventory formats. + + + + + + + +
+ + + Use of "Using" @@ -1300,7 +1563,7 @@ Numbers (move from N entry) --> For times of day, use uppercase without periods, such as "11 AM". Use a nonbreaking space between the numeral and "AM" or "PM". - + Use "noon" or "12 noon" instead of "12 PM". diff --git a/en-US/New.xml b/en-US/New.xml index 9a1a58e..d35bcff 100644 --- a/en-US/New.xml +++ b/en-US/New.xml @@ -5,6 +5,111 @@ ]>
New in This Release + + Release 6.0 + Major update in December 2022 to add further style and grammar guidance: + + + + Added audience information for this guide. + + + Updated guidance about the use of verbs in titles. + + + Updated guidance about the use of captions or callouts in figures. + + + Avoid redundant words. + + + Avoid a causative verb. + + + Words to use with countable nouns. + + + Use of "either-or" construction. + + + Avoid stating that something is easy to do or to use. + + + Avoid first person. + + + Use "following" with a noun. + + + Avoid hyphenating with an "-ly" prefix: added an example. + + + If-Then statements. + + + Make a full lead-in sentence to introduce a list. + + + Making list items parallel. + + + Updated guidance about use of compact lists. + + + Using noun strings. + + + Avoid a noun followed by an "-ing" word. + + + Using object names. + + + Placement of "only". + + + Preposition at the end of a sentence. + + + Use straight rather than curly quotation marks. + + + Avoid "(s)" for plural. + + + Added further examples of slang, idioms, and metaphors to avoid. + + + Avoid a slash. + + + Spacing with a unit of measurement. + + + Improved succinctness examples. + + + Avoid "there is", "there are". + + + Use "this", "that", "these", "those" with a noun. + + + Replaced use of "$" as a variable marker in this guide to use angle brackets instead. + + + Use of "whether" versus "if". + + + New or updated usage entries: like, once, unset, while. + + + Various other fixes. + + + + + Release 5.1 Minor update in January 2022 to address some reported issues: diff --git a/en-US/O.xml b/en-US/O.xml index 6bffc0d..49ce877 100644 --- a/en-US/O.xml +++ b/en-US/O.xml @@ -94,6 +94,12 @@ Use only to mean "one time". Do not use as a conjunction to mean "after" or "when". + + Example 1: Instead of "Once the name is set for a network interface on the system, the name of the interface does not change", use "When the name is set for a network interface on the system, the name of the interface does not change". + + + Example 2: Instead of "Once you generate the SSH keys, you can find them by default in the .ssh/ directory", use "After you generate the SSH keys, you can find them by default in the .ssh/ directory". + diff --git a/en-US/Preface.xml b/en-US/Preface.xml index 37932d5..703391e 100644 --- a/en-US/Preface.xml +++ b/en-US/Preface.xml @@ -5,6 +5,9 @@ ]> Preface + + + diff --git a/en-US/Punctuation.xml b/en-US/Punctuation.xml index 67c3a96..1ec0e8c 100644 --- a/en-US/Punctuation.xml +++ b/en-US/Punctuation.xml @@ -422,6 +422,50 @@ If the contents of the parentheses include at least one complete sentence, the period goes inside the parentheses. If not, the period goes outside. + + Do not use "(s)" in parentheses to denote a plural. If something can be singular or plural, make it plural. + + + + + + + + + + + Example + Improvement + + + + + + + Choose the item(s). + Choose the items. + + + + + + + +
+ +
+
+ Slashes + + Avoid use of a slash character to mean either of two options. + + + For example, instead of "enable/disable", use "enable or disable". + + + Instead of "A and/or B", use "A or B", or "A, or B, or both". + +
Quotation Marks @@ -433,7 +477,11 @@ Question marks, exclamation points, dashes, and semicolons go inside the quotation marks if they are part of the quotation; if not, they go outside. --> - + + When indicating the start or end of a direct quotation, use curly quotation marks. + In all other contexts, such as when writing code samples, code syntax, hexadecimal numbers, or hypertext links, use straight quotation marks. + Refer to the "Typographical Considerations" section in the "Quotation Marks" topic in the IBM Style Guide. + In technical documentation, place punctuation marks, including periods, commas, question marks, exclamation points, dashes, and semicolons inside the quotation marks if they are part of the quotation or part of a programming element that uses quotation marks; if not, place punctuation marks outside the quotation marks. If a sentence ends with a quotation, use only one punctuation mark to end the sentence, and place it inside the closing quotation mark if it is part of the quotation, or outside if it is not. @@ -533,7 +581,7 @@ Deleted paragraph now that DocBook tagging no longer applies. --> Referring to Punctuation Marks - 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. The path contains the library qualifier in braces. diff --git a/en-US/S.xml b/en-US/S.xml index c2b66bf..46da1b8 100644 --- a/en-US/S.xml +++ b/en-US/S.xml @@ -534,7 +534,7 @@ a programming and technical sense, it also means "Run the source - More generally, avoid use of "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL". + More generally, avoid "SQL" as a generic marker if possible. When discussing MySQL, write "MySQL". When discussing Microsoft SQL Server, write "Microsoft SQL Server". When discussing PostgreSQL (which is pronounced pŏstgrĕs kyü ĕl), write "PostgreSQL". diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 7800861..0093639 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -71,19 +71,16 @@ You can nest lists, but try to keep the number of levels to two or fewer. To nest procedures in DocBook, use <substep> elements. -
Formatting Lists for Readability 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 or attributes to specify the spacing between list items. - DocBook uses the spacing attribute by default. - - 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: @@ -112,10 +109,12 @@ - The following discussion provides some initial insight into using lists correctly. See the IBM Style Guide for a full discussion. + + Do not insert a list midway through a sentence and then continue the sentence after the list. + @@ -180,13 +179,172 @@
+ + For a lead-in sentence that introduces a list, use a complete sentence. A lead-in that is a sentence fragment can be difficult to translate into other languages. + + + + + + + + + Example + Improvement + + + + + + + + Non-privileged users can use the role to configure: + + + + + Interface 1 + + + + + + Interface 2 + + + + + + + + Non-privileged users can use the role to configure the following interfaces: + + + + + Interface 1 + + + + + + Interface 2 + + + + + + + + + + + + + +
+ + + Make items in a list grammatically parallel. + + + In the following example, the original three list items inconsistently use an infinitive verb form, and then a gerund, and then an imperative. In the improved example, all three list items consistently use an imperative statement. + + + + + + + + + Example + Improvement + + + + + + + + + + + To obtain the file name of the default kernel with the grubby command: + + + ... + + + + + + Finding the index number of the default kernel: + + + ... + + + + + + Use the grubby command to persistently change the default kernel: + + + ... + + + + + + + + + + + Obtain the file name of the default kernel with the grubby command: + + + ... + + + + + + Find the index number of the default kernel: + + + ... + + + + + + Use the grubby command to persistently change the default kernel: + + + ... + + + + + + + + + + + + + +
+
Noun Stacking - Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. + Modifier strings (modifier + noun + noun sentence format) and over-modified nouns (or noun stacks) are especially difficult to translate, particularly when several different combinations might make sense. Avoid a stack of more than three consecutive nouns. @@ -213,6 +371,41 @@ For new users, set the parameters to the default printer configuration. Enter the maximum length of time, in number of days, that you want to keep the address lists updated by automatic synchronization. Then, press Enter. + + Standard system log management configuration rotates log files every week. + Standard configuration of system log management rotates log files every week. + + + + + + + +
+ + Avoid a noun followed by a word that ends in -ing. Such a construction is difficult to translate. + + + + + + + + + + Example + Improvement + + + + + + + The nmap utility scans privileged TCP ports looking for services. + The nmap utility scans privileged TCP ports to look for services. + + + diff --git a/en-US/U.xml b/en-US/U.xml index 5e4f2a9..935a9f1 100644 --- a/en-US/U.xml +++ b/en-US/U.xml @@ -77,6 +77,9 @@ This rule matches only TCP packets where the SYN flag is set and the ACK flag is cleared. + + Unset the ANSIBLE_NAVIGATOR_CONFIG environment variable so that the remaining exercises use the project's ./ansible-navigator.yml settings file. + diff --git a/en-US/W.xml b/en-US/W.xml index 136935a..7543d1b 100644 --- a/en-US/W.xml +++ b/en-US/W.xml @@ -92,6 +92,31 @@ + + + whether + + + Use “whether” instead of “if” to refer to a choice or to alternatives. + For example, instead of "Test if authenticated FTP access is restored", write "Test whether authenticated FTP access is restored". + + + + + + + + while + + + In technical content, use “while” only to indicate that many tasks or processes occur at the same time. + For example, instead of "While most targets use one target portal group (TPG), advanced configurations might define multiple TPGs", write "Although most targets use one target portal group (TPG), advanced configurations might define multiple TPGs". + + + + + + whitelist diff --git a/index.html b/index.html index dba7a4f..c03c6a3 100644 --- a/index.html +++ b/index.html @@ -2,7 +2,7 @@ - Stylepedia.net + Red Hat Style Guide @@ -41,30 +41,18 @@

- The official style guide for Red Hat technical documentation, including how to write for translation, common mistakes to avoid, rules for everyday punctuation, and grammar. -

-

- A dedicated guide to Docbook XML as used in Red Hat Training courses. + The official style guide for Red Hat technical documentation, including how to write for translation, common mistakes to avoid, rules for everyday punctuation, grammar, and much more.

- - Red Hat Technical Writing Style Guide v5.1 + + Red Hat Technical Writing Style Guide v6.0

-

- - Red Hat Technical Writing Style Guide v5.0 -

- - + + Red Hat Technical Writing Style Guide v5.1 -

- - RHT DocBook XML Guide v4.0 -

-

Red Hat Brand Standards