template-update updated with JH comments

Author: “Emily

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

@@ -8,7 +8,7 @@ ifdef::context[:parent-context: {context}]
 
 
 ////
-Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA element.
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
 ////
 :_mod-docs-content-type: ASSEMBLY
 
@@ -18,23 +18,19 @@ Metadata attribute that will help enable correct parsing and conversion to the a
 * ID: [id="assembly-my-user-story_{context}"]
 * Title: = My user story
 
-The ID is an anchor that links 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
+ID is a unique identifier that can be used to reference this assembly. 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.
 
-////
 Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction.
-
 If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 ////
-
-:context: assembly-keyword
-
+[id="assembly-my-user-story_{context}"]
+= My user story
 ////
 The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
 ////
 
+:context: assembly-keyword
+
 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.
 
 == Prerequisites
@@ -47,16 +43,15 @@ This paragraph is the assembly introduction. It explains what the user will acco
 
 ////
 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.
+
+ Add a blank line after each 'include::' statement.
 ////
 
+include::modules/TEMPLATE_CONCEPT_explaining_a_concept.adoc[leveloffset=+1]
+
 include::modules/TEMPLATE_PROCEDURE_doing_one_procedure.adoc[leveloffset=+2]
-// Add a blank line after each 'include::' statement.
 
 include::modules/TEMPLATE_PROCEDURE_reference-material.adoc[leveloffset=+2]
 

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

@@ -1,5 +1,5 @@
 ////
-Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA element.
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
 ////
 
 :_mod-docs-content-type: CONCEPT
@@ -10,17 +10,17 @@ Base the file name and the ID on the module title. For example:
 * ID: [id="my-concept-module-a_{context}"]
 * Title: = My concept module A
 
-The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+ ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken.
 
 The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+
+Be sure to include a line break between the title and the module introduction.
 ////
 
 [id="my-concept-module-a_{context}"]
 = 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 or gerund. See also _Wording of headings_ in _IBM Style_.
-
-Be sure to include a line break between the title and the module introduction.
 ////
 
 Write a short introductory paragraph that provides an overview of the module.

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

@@ -1,6 +1,6 @@
 
 ////
-Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA element.
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
 ////
 
 :_mod-docs-content-type: PROCEDURE
@@ -11,16 +11,17 @@ Base the file name and the ID on the module title. For example:
 * ID: [id="doing-procedure-a_{context}"]
 * Title: = Doing procedure A
 
-The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+ ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken.
 
 The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+
+Be sure to include a line break between the title and the module introduction.
 ////
 
 [id="doing-procedure-a_{context}"]
 = Doing procedure A
 ////
 Start the title of a procedure module with a gerund, such as Creating, Installing, or Deploying.
-Be sure to include a line break between the title and the module introduction.
 ////
 
 Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization.

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

@@ -1,5 +1,5 @@
 ////
-Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA element.
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
 ////
 :_mod-docs-content-type: REFERENCE
 
@@ -9,17 +9,18 @@ Base the file name and the ID on the module title. For example:
 * ID: [id="my-reference-a_{context}"]
 * Title: = My reference A
 
-The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+ ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken.
 
 The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+
+Be sure to include a line break between the title and the module introduction.
 ////
 
 [id="reference-material_{context}"]
 = 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.
-
-Be sure to include a line break between the title and the module introduction.
+on.
 ////
 
 Write a short introductory paragraph that provides an overview of the module.