doc-guidelines-rt

Author: dfitzmau

contributing_to_docs/doc_guidelines.adoc

@@ -59,6 +59,11 @@ toc::[]                                                         <7>
 <6> A blank line. You *must* have a blank line here before the toc.
 <7> The table of contents for the current assembly.
 
+[NOTE]
+====
+Do not use backticks or other markup in assembly or module headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
+====
+
 After the heading block and a single whitespace line, you can include any content for this assembly.
 
 [NOTE]
@@ -101,6 +106,11 @@ Example:
 = Basic CLI commands
 ----
 
+[NOTE]
+====
+Do not use backticks or other markup in assembly or module headings. You can use backticks or other markup in the title for a block, such as a code block `.Example` or a table `.Description` title.
+====
+
 [id="snippet-file-metadata"]
 == Text snippet file metadata
 Every text snippet should be placed in the `snippets/` folder and should contain the following metadata at the top:
@@ -247,6 +257,8 @@ Do not use "Overview" as a heading.
 
 Do not use backticks or other markup in assembly or module headings.
 
+Do not use special characters or symbols in titles. Symbols and special characters in titles can cause rendering errors in the HTML output.
+
 Use only one level 1 heading (`=`) in any file.
 
 === Discrete headings
@@ -538,6 +550,28 @@ If it makes more sense in context to refer to the major version of the product i
 Other common attribute values are defined in the `_attributes/common-attributes.adoc` file. Where possible, generalize references to those values by using the common attributes. For example, use `{cluster-manager-first}` to refer to Red Hat OpenShift Cluster Manager. If you need to add an attribute to the `_attributes/common-attributes.adoc` file, open a pull request to add it to the attribute list. Do not create a separate attributes file without first consulting the docs team.
 ====
 
+[id="third-party-vendor-product-names"]
+== Third-party vendor product names
+
+Red Hat integrates with many third-party vendor products. For certain integrated products, third-party vendor staff might have access to certain Red Hat resources and be contactable within Red Hat. On other occasions, common open-source products might be widely used across IT infrastructure providers, so Red Hat might not have direct contacts to organizations that own these products.
+
+Depending on the third-party vendor's requirements, you might need to add a registered trademark symbol to all of the vendor's product names or only on the first occurence of referencing the product name in an assembly, a module, or a document.  
+
+Choose any of the following sources for clarification on using the symbol for a specific third-party vendor product name:
+
+* Visit the third-party vendor's website and contact them directly.
+* Contact internal Red Hat product teams or integrated third-party vendor teams.
+* Contact the Red Hat Legal team. Only consider this option when the other two options did not provide clear context for your query.
+
+[IMPORTANT]
+====
+Do not use Asciidoctor character replacement substitutions, which rely on a Unicode code point such as _&#174;_, to set the registered symbol in an Asciidoc file. Instead use _(R)_ beside the product name. For example, `IBM(R) LinuxONE`.
+
+Do not apply any superscript, such as `(R)`, or subscript formatting to module or assembly headings.
+====
+
+For more information about contacting the Red Hat's Legal team, see link:https://source.redhat.com/departments/legal/redhatintellectualproperty/trademarks/trademarks_and_domain_names_wiki/copyright_notices_and_trademark_legends[Copyright Notices and Trademark Legends] on the The Source.
+
 //CANARY
 [id="conditional-content"]
 == Conditional content