issue-126 updated the comments and removed the uncommented templates

Author: emmurphy1

modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc

@@ -2,47 +2,71 @@
 //
 // <List assemblies here, each on a new line>
 
-// Retains the context of the parent assembly if this assembly is nested within another assembly.
-// For more information about nesting assemblies, see: https://redhat-documentation.github.io/modular-docs/#nesting-assemblies
-// See also the complementary step on the last line of this file.
+////
+Retains the context of the parent assembly if this assembly is nested within another assembly.
+For more information about nesting assemblies, see: https://redhat-documentation.github.io/modular-docs/#nesting-assemblies
+See also the complementary step on the last line of this file.
+////
+
 ifdef::context[:parent-context: {context}]
 
-// Base the file name and the ID on the assembly title. For example:
-// * file name: assembly-my-user-story.adoc
-// * ID: [id="assembly-my-user-story_{context}"]
-// * Title: = My user story
+////
+ Base the file name and the ID on the assembly title. For example:
+* file name: assembly-my-user-story.adoc
+* ID: [id="assembly-my-user-story_{context}"]
+* Title: = My user story
+
+The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken. Include {context} in the ID so the assembly can be reused.
+////
 
-// The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken. Include {context} in the ID so the assembly can be reused:
 [id="assembly-my-user-story_{context}"]
 = My user story
-//If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
+////
+If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
+////
+
 :context: assembly-keyword
-// The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+
+////
+The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+////
 
 [role="_abstract"]
 This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. The `[role="_abstract"]` tag defines the first paragraph of the introduction for search metadata.
 
 .Prerequisites
-//Prerequisites are optional. Delete if your assembly has no prerequisites.
+////
+Prerequisites are optional. Delete if your assembly has no prerequisites.
+////
 
 * X is installed. For information about installing X, see <link>.
 * You can log in to X with administrator privileges.
 
-// The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
+////
+The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
+////
 
 include::modules/TEMPLATE_CONCEPT_explaining_a_concept.adoc[leveloffset=+1]
-// [leveloffset=+1] ensures that when a module title is a level 1 heading (= Title), the heading will be interpreted as a level-2 heading (== Title) in the assembly. Use [leveloffset=+2] and [leveloffset=+3] to nest modules in an assembly.
+
+////
+[leveloffset=+1] ensures that when a module title is a level 1 heading (= Title), the heading will be interpreted as a level-2 heading (== Title) in the assembly. Use [leveloffset=+2] and [leveloffset=+3] to nest modules in an assembly.
+////
 
 include::modules/TEMPLATE_PROCEDURE_doing_one_procedure.adoc[leveloffset=+2]
 include::modules/TEMPLATE_PROCEDURE_reference-material.adoc[leveloffset=2]
 
 [role="_additional-resources"]
 == Additional resources (or Next steps)
-//Optional
+////
+Optional. Delete if not used.
+////
+
 * A bulleted list of links to other material closely related to the contents of the assembly, including xref links to other assemblies in your collection.
 * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 
-// Restore the context to what it was before this assembly.
+////
+Restore the context to what it was before this assembly.
+////
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]

modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc

@@ -2,17 +2,27 @@
 //
 // <List assemblies here, each on a new line>
 
-// Base the file name and the ID on the module title. For example:
-// * file name: con-my-concept-module-a.adoc
-// * ID: [id="con-my-concept-module-a_{context}"]
-// * Title: = My concept module A
+////
+Base the file name and the ID on the module title. For example:
+* file name: con-my-concept-module-a.adoc
+* ID: [id="con-my-concept-module-a_{context}"]
+* Title: = My concept module A
+////
+
+////
+The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+ ////
 
-// The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
 [id="con-my-concept-module-a_{context}"]
-// The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+
+////
+The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+////
+
 = My concept module A
-//In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly.
-//Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_.
+////
+In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly. Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_.
+////
 
 [role="_abstract"]
 A short introductory paragraph that provides an overview of the module is required.
@@ -26,7 +36,9 @@ The contents of a concept module give the user descriptions and explanations nee
 
 [role="_additional-resources"]
 .Additional resources
-//Optional
+////
+Optional. Delete if not used.
+////
 * A bulleted list of links to other material closely related to the contents of the concept module.
 * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
 * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc

@@ -2,16 +2,25 @@
 //
 // <List assemblies here, each on a new line>
 
-// Base the file name and the ID on the module title. For example:
-// * file name: proc-doing-procedure-a.adoc
-// * ID: [id="doing-procedure-a_{context}"]
-// * Title: = Doing procedure A
+////
+Base the file name and the ID on the module title. For example:
+* file name: proc-doing-procedure-a.adoc
+* ID: [id="doing-procedure-a_{context}"]
+* Title: = Doing procedure A
+////
+ The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+////
 
-// The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
 [id="proc-doing-one-procedure_{context}"]
-// The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+
+////
+The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+////
+
 = Doing one procedure
-// Start the title of a procedure module with a verb, such as Creating or Create. See also _Wording of headings_ in _The IBM Style Guide_.
+////
+Start the title of a procedure module with a verb, such as Creating or Create. See also _Wording of headings_ in _The IBM Style Guide_.
+////
 
 [role="_abstract"]
 A short introductory paragraph that provides an overview of the module is required. Procedure modules should include both what users will do and why users want to do it.
@@ -32,7 +41,9 @@ The `[role="_abstract"]` tag defines the first paragraph of the module for searc
 . Use an unnumbered bullet (*) if the procedure includes only one step.
 
 .Verification steps
-//Optional. Delete if not applicable. Provide the user with verification methods for the procedure, such as expected output or commands that can be used to check for success or failure.
+////
+Optional. Delete if not applicable. Provide the user with verification methods for the procedure, such as expected output or commands that can be used to check for success or failure.
+////
 
 . Start each step with an active verb.
 
@@ -43,7 +54,9 @@ The `[role="_abstract"]` tag defines the first paragraph of the module for searc
 
 [role="_additional-resources"]
 .Additional resources
-//Optional
+////
+Optional. Delete if not used.
+////
 * A bulleted list of links to other material closely related to the contents of the procedure module.
 * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
 * For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc

@@ -2,16 +2,23 @@
 //
 // <List assemblies here, each on a new line>
 
-// Base the file name and the ID on the module title. For example:
-// * file name: ref-my-reference-a.adoc
-// * ID: [id="ref-my-reference-a_{context}"]
-// * Title: = My reference A
+////
+Base the file name and the ID on the module title. For example:
+* file name: ref-my-reference-a.adoc
+* ID: [id="ref-my-reference-a_{context}"]
+* Title: = My reference A
+
+The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+////
 
-// The ID is used as an anchor for linking to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
 [id="ref-reference-material_{context}"]
-// The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+////
+The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide
+////
 = Reference material
-//In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly.
+////
+In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly.
+////
 
 [role="_abstract"]
 A short introductory paragraph that provides an overview of the module is required.