diff --git a/en-US/Book_Design.xml b/en-US/Book_Design.xml index ca49a26..6849ac1 100644 --- a/en-US/Book_Design.xml +++ b/en-US/Book_Design.xml @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]>
- Overall Book Design + Overall Publication Design This section describes a general approach to the overall layout and design of technical documentation. This design was developed specifically for technical documentation and might not suit content produced by other groups. @@ -34,6 +34,12 @@ Introductions + + + + Placement of headings + + @@ -48,10 +54,10 @@
Titles and Subtitles - The title should be a combination of the complete product name, its version, and the name of the book. For example, "Red Hat Satellite 5.6 Installation Guide", or "Red Hat Enterprise Linux 6 Deployment Guide". + The title should be a combination of the complete product name, its version, and the name of the publication. For example, "Red Hat Satellite 6.12 Installation Guide", or "Red Hat Enterprise Linux 9 Deployment Guide". - The subtitle should be a single, succinct phrase that describes the intent of the book; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 8 for all architectures". + The subtitle should be a single, succinct phrase that describes the intent of the publication; an abstract of the abstract. For example, "Installing Red Hat Enterprise Linux 9 for All Architectures".
@@ -71,23 +77,23 @@ - A suitable abstract covers the high-level topics of the book, and is probably a good place to mention the audience. It should cover the following basics: + A suitable abstract covers the high-level topics of the publication, and is probably a good place to mention the audience. It should cover the following basics: - What: What is the purpose of the book or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." + What: What is the purpose of the publication or document? A brief summary, for example, "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API." - How: How does the book convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." + How: How does the publication convey its content? That is, is it task-based? Example-driven? A reference guide? For example, "The guide explains each API method and demonstrates examples of data models for input and output." - Why (and possibly Who): A basic rationale for why this book exists, and its audience (and elaborate on the target audience inside the book). For example, "This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + Why (and possibly Who): A basic rationale for why this publication exists, and its audience (and elaborate on the target audience inside the publication). For example, "This publication provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." @@ -101,17 +107,17 @@ "The Red Hat Satellite 5.6 API Guide is a full reference for Satellite's XMRPC API. The guide explains each API method and demonstrates examples of data models for input and output. - This book provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." + This publication provides a basis for administrators and developers to write custom scripts and to integrate Red Hat Satellite with third-party applications." - Update or modify each component according to the type of book that you are writing. + Update or modify each component according to the type of publication that you are writing.
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 <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. + The term "introduction" on its own is sufficiently vague, and raises enough questions in translation and with translation memory 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 publication to introduce the reader to the product. Do not use "Introduction" to introduce the publication; 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.
diff --git a/en-US/Cross_references.xml b/en-US/Cross_references.xml index 623cb63..4eac3d0 100644 --- a/en-US/Cross_references.xml +++ b/en-US/Cross_references.xml @@ -11,7 +11,7 @@ Formatting is not described in this section. - In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed book, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader. + In the days of print-only documentation, cross-references referred readers to additional or related information that existed elsewhere in the physical printed publication, on other pages. The readers had to physically turn pages to find the referenced page, so authors, editors, and proofreaders developed a certain caution about scattering cross-references through the text. Despite the ease of use and creation of cross-references and links in online documents today, the author must still do the work for the reader. The author must still do the heavy lifting and arrange the information so that the reader can absorb it in the smoothest possible fashion. Forcing the reader to leap from link to link might indicate that the author is writing for their own ease, and not for the good of the reader.
The Additional Information Test diff --git a/en-US/Design.xml b/en-US/Design.xml index 9ca9f2a..f5af674 100644 --- a/en-US/Design.xml +++ b/en-US/Design.xml @@ -15,7 +15,8 @@ Capitalization - The standard for all Red Hat technical documentation is title case for all headings and titles. + The standard for technical documentation is title case for all headings and titles. + Table titles and procedure titles fall into this category; standard title case capitalization rules apply. @@ -32,7 +33,7 @@ Marketing and Brand Capitalization Guide - The Red Hat Marketing and Brand groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. + The Red Hat Marketing and Brand groups and some other groups use sentence case for most titles and headings, with some exceptions, for example, when referencing an externally produced resource's title. @@ -61,6 +62,9 @@ In some cases, a verb might not be appropriate because the content is purely informational. Instead of using a vague verb like "Understanding", "Describing", "Introducing", or "Exploring", either use a more specific verb, or use a noun phrase instead of a verb. A noun phrase is descriptive and omits a verb, for example "Installation Overview" or "The OpenShift Web Console." + + Avoid a title that consists of only one word. + @@ -85,6 +89,11 @@ Cluster Updates + + MetalLB + The MetalLB Component + + @@ -106,13 +115,39 @@ File Names, Commands, and Related Terms - When creating chapter and section titles, do not include file, command, or similar names, and do not include markup elements. + When creating chapter and section titles, do not include file, command, or similar names, and generally do not include markup elements. Instead, focus on the task at hand and introduce the required file and command names in the text. Including such objects in titles is generally considered poor technical writing practice. Depending on how your documentation is built and delivered, including these object types can result in unpredictable results and can even cause failed builds. +
+ + + + + + + Example + Improvement + + + + + + + Custom Domains and cert-manager Operators with ROSA + Custom Domains and Certificate Management Operators with ROSA + + + + + + + +
+
Documenting Fonts @@ -445,7 +480,7 @@ $ vi myFile.txt @@ -714,7 +749,7 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
Using Extended User and Group Names - Sometimes, the recommended list of user and group names is too restrictive for the scope of a book or article. In such cases, the following extended model is acceptable. + Sometimes, the recommended list of user and group names is too restrictive for the scope of a publication or article. In such cases, the following extended model is acceptable. Using Realistic Usernames @@ -1338,9 +1373,9 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest
Citing Other Works - Referencing Other Books + Referencing Other Publications - When referencing another book, either internal or external to Red Hat, use the following format: + When referencing another publication, either internal or external to Red Hat, use the following format: @@ -1349,8 +1384,8 @@ STEP 14: COMMIT ...output omitted... localhost/nexus:latest --> - -Book Title by First name Surname; Publisher. + +Publication Title by First name Surname; Publisher. diff --git a/en-US/Language.xml b/en-US/Language.xml index 9c05b08..384d379 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -1628,7 +1628,7 @@ Spell out the following number types: numbers zero through nine, any number that begins a sentence, a number that precedes another number (four 6-pound bags; eleven 20-pound bags), approximations (thousands of ...), and very large values. - Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to book sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). + Use numerals for numbers 10 and greater, and for numbers less than 10 if they appear in the same paragraph as numbers of 10 or greater (for example, "You answered 8 out of 14 questions correctly"). Use numerals for negative numbers, fractions, percentages, decimals, measurements, and references to publication sections (for example, Chapter 3, Table 5, Page 11). Also use numerals when referring to registers (such as R1), code (such as x = 6), and release versions (such as Red Hat Enterprise Linux 8, Linux kernel 4.18). Do not use commas in numbers with four digits (use 1000 rather than 1,000). Use commas, to separate groups of three digits, in numbers with five or more digits (such as 10,000; 123,456,789; 1,000,000,000). diff --git a/en-US/Translation.xml b/en-US/Translation.xml index 726b582..c59c81d 100644 --- a/en-US/Translation.xml +++ b/en-US/Translation.xml @@ -678,7 +678,7 @@ Entities can be helpful in some cases, but they are more of a hindrance when used for terms that need translation. Translators must compare the string with the built document to determine what the entity stands for. These entities might even be overlooked and not be translated at all. - To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a book. Required entities vary by brand; only the following entities are required for a standard book: + To avoid issues with incorrect or outdated entity values, problems with translation, and so on, only include the entities that are required to build your books. If you use Publican () to create and maintain your documentation, it creates and populates the required entities with default values when you create a publication. Required entities vary by brand; only the following entities are required for a standard publication: