Merge pull request #72091 from libander/include-by-tag-suggestion

OSDOCS-9770 - [Meta] - Proposed change to including content using tags.

Author: skrthomas

contributing_to_docs/doc_guidelines.adoc

@@ -28,7 +28,7 @@ It is not necessary to update existing content to unwrap lines, but you can remo
 +
 [TIP]
 ====
-In the Atom editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragraph.
+In the Pulsar editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragraph.
 ====
 
 [id="assembly-file-metadata"]
@@ -358,7 +358,31 @@ The following examples include IDs that are unique to the "Configuring alert not
 ----
 
 == Writing assemblies
-An _assembly_ is a collection of modules that describes how to accomplish a user story.
+An _assembly_ is a collection of modules that describes how to accomplish a user story. Module content is added to an assembly using the `include` directive. The `include` directive includes contents from another file in the current document. Files can be modules or snippets formatted in AsciiDoc, or another text format such as YAML.
+
+An `include` directive must always be on its own line.
+
+.Standard module include syntax
+[source,text]
+====
+\include::modules/module-filename.adoc[leveloffset=+1] <1>
+====
+<1> [leveloffset=] link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/#manipulate-heading-levels-with-leveloffset[is relative], and changes the header level of included content.
+
+You can use `tag` attributes to link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions[define regions of a file and include by tag instead of the whole file.] This enables you to make conditional modifications to existing modules instead of duplicating content. When creating a tag, use a tag name that makes it easy to understand where the content defined will be included.
+
+.Tagged module include syntax
+[source,text]
+====
+\include::modules/module-with-tags-filename.adoc[leveloffset=+1,tag=TagName]
+====
+
+You can filter out the regions defined by a `tag` attribute by using link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/#tag-filtering[expressions] in place of or in conjunction with the tag name. If you add tag defined conditional content to a module with no existing tags, you must update existing includes of the file you are changing to exclude your content.
+
+[IMPORTANT]
+====
+Including link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-lines/[lines by content ranges] can lead to content errors when the included file is subsequently updated and is not permitted.
+====
 
 Avoid link:https://redhat-documentation.github.io/modular-docs/#nesting-assemblies[nesting assemblies] in other assembly files. You can create more complicated document structures by modifying the link:https://github.com/openshift/openshift-docs/tree/main/_topic_maps[topic maps].
 
@@ -401,11 +425,6 @@ When needed, use `.Prerequisites`, `.Next steps`, or `.Additional resources` syn
 == 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.
 
-[IMPORTANT]
-====
-Only include entire snippets in an assembly or module. Including link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-lines/[lines by content ranges] can lead to content errors when the included file is subsequently updated and is not permitted.
-====
-
 In the context of modules and assemblies, text snippets do not include headings or anchor IDs. Text snippets also cannot contain xrefs. This type of component is text only. Examples include the following:
 
 * Admonitions that appear in multiple modules.