Merge pull request #38393 from mjpytlak/textsnippet

Adding guidance on text snippets

Author: kalexand-rh

contributing_to_docs/doc_guidelines.adoc

@@ -85,6 +85,38 @@ Example:
 = Basic CLI commands
 ----
 
+== Text snippet file metadata
+Every text snippet should be placed in the snippets folder and should contain the following metadata at the top:
+
+----
+// Text snippet included in the following assemblies: <1>
+//
+// * list of assemblies where this text snippet is included
+//
+// Text snippet included in the following modules:    <2>
+//
+// * list of modules where this text snippet is included
+----
+<1> List of assemblies in which this text snippet is included.
+<2> List of modules in which this text snippet is included.
+
+[NOTE]
+====
+An anchor ID and human readable title are not required metadata. This type of component is text only and not intended to be published or cross referenced on its own. See <<writing-text-snippets>>.
+====
+
+Example:
+
+----
+// Text snippet included in the following assemblies:
+//
+// * installing/installing_aws/installing-aws-default.adoc
+// * installing/installing_azure/installing-azure-default.adoc
+// * installing/installing_gcp/installing-gcp-default.adoc
+
+In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.
+----
+
 == Assembly/module file names
 
 Try to shorten the file name as much as possible _without_ abbreviating important terms that may cause confusion. For example, the `managing-authorization-policies.adoc` file name would be appropriate for an assembly titled "Managing Authorization Policies".
@@ -97,6 +129,7 @@ When creating a new directory or subdirectory, you must create two symbolic link
 
 * An `images` symbolic link to the top-level `images/` directory
 * A `modules` symbolic link to the top-level `modules/` directory
+* If you are including a text snippet in your modules or assemblies, a `snippets` symbolic link to the top-level `snippets/` directory
 
 If the directory that contains an assembly does not have the `images` symbolic link, any images in that assembly or its modules will not be included properly when building the docs.
 
@@ -259,6 +292,34 @@ link:https://redhat-documentation.github.io/modular-docs/#creating-procedure-mod
 When needed, use `.Prerequisites`, `.Next steps`, or `.Additional resources` syntax to suppress TOC formatting within a module. Do not use `==` syntax for these headings in modules. Because you cannot use the xrefs in modules, if you need to include a link under one of these headings, place the entire subsection in the assembly instead.
 ====
 
+[id="writing-text-snippets"]
+== Writing text snippets
+A _text snippet_ is an optional component that lets you reuse content in multiple modules and assemblies. Text snippets are not a substitute for modules, but instead are a more granular form of content reuse. While a module is content that a reader can understand on its own (like an article) or as part of a larger body of work (like an assembly), a text snippet is not self-contained and is not intended to be published or cross referenced on its own.
+
+In the context of modules and assemblies, text snippets do not include headings or anchor IDs. This type of component is text only. Examples include the following:
+
+* Admonitions that appear in multiple modules.
+* An introductory paragraph that appears in multiple assemblies.
+* The same series of steps that appear in multiple procedure modules.
+* A deprecation statement that appears in multiple sets of release notes.
+
+Example:
+
+You could write the the following paragraph once and include it in each assembly that explains how to install a cluster using the installer-provisioned default values:
+
+[source,text]
+----
+In {product-title} version {product-version}, you can install a cluster on {cloud-provider-first} ({cloud-provider}) that uses the default configuration options.
+----
+
+[NOTE]
+====
+In the example, `cloud-provider-first` and `cloud-provider` are not defined by the `common-attributes` module. If you use an attribute that is not common to OpenShift docs, make sure to define it locally in either the assembly or module, depending on where the text snippet is included.
+====
+
+For more information about creating text snippets, see the
+link:https://redhat-documentation.github.io/modular-docs/#using-text-snippets[Red Hat modular docs reference guide]
+
 [id="using-conscious-language"]
 == Using conscious language