redhat-documentation · emmurphy1 · Aug 1, 2023 · Jul 10, 2023 · Jul 10, 2023 · Jul 12, 2023
@@ -1,5 +1,5 @@
 [id="creating-concept-modules"]
-= Creating concept modules
+= Concept modules
 
 This section explains what a concept module is and provides recommended practices for writing concept modules.
 

@@ -2,7 +2,16 @@
 
 = Procedure modules
 
-Procedure modules explain how to do something. A procedure module contains numbered, step-by-step instructions to help the user accomplish a single task. Sometimes those tasks include substeps. Procedure modules must include a title, a brief introduction, and one or more steps in the form of imperative statements. Procedure modules can also contain prerequisites, verification steps, and additional resources or next steps.
+Procedure modules explain how to do something. A procedure module contains numbered, step-by-step instructions to help users accomplish a single task. Sometimes those tasks include substeps. Procedure modules must include a title, a brief introduction, and one or more steps in the form of imperative statements. Procedure modules can also contain the following sections:
+
+* xref:limitations[]
+* xref:prerequisites[]
+* xref:verification[]
+* xref:troubleshooting[]
+* xref:next-steps[]
+* xref:additional-resources[]
+
+Do not change or embellish these subheadings. Unless absolutely necessary, do not create additional subheadings.
 
 .Schema of a procedure module
 image::procedure-diagram.png[]
@@ -18,29 +27,49 @@ The introduction typically provides context for the procedure, such as:
 * Why and where the user performs the procedure
 * Special considerations specific to the procedure
 
-.Procedure prerequisites
-This section is optional. Prerequisites are a bulleted list of conditions that must be satisfied before the user starts the procedure. Use a bulleted list for prerequisites and the plural heading *Prerequisites*, even if you only have a single prerequisite.
+[id="limitations"]
+.Limitations
+This section is optional and not used often. If there are any limitations that affect the procedure, list them in this section. Use a bulleted list for limitations and the plural heading *Limitations*, even if your procedure only has a single limitation.
+
+[id="prerequisites"]
+.Prerequisites
+This section is optional. Prerequisites are a bulleted list of conditions that must be satisfied before the user starts the procedure. Use a bulleted list for prerequisites and the plural heading *Prerequisites*, even if your procedure only has a single prerequisite.
 
 Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel.
 
 Focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites. If a prerequisite applies to all of the procedures in a user story, consider listing the prerequisite in the assembly file. If you do this, consider including the prerequisite in the procedure module as a comment.
 
-.Procedure steps
-The procedure consists of one or more steps required to complete the procedure. Each step describes one action. For single-step procedures, use an unnumbered bullet instead of a numbered list.
+[id="procedure"]
+.Procedure
+This section is required. The procedure consists of one or more steps required to complete the procedure. Each step describes one action written in the imperative form, for example, 'Do this action'. For single-step procedures, use an unnumbered bullet instead of a numbered list.
 
 NOTE: Not all numbered lists in documentation are procedures. You can also use numbered lists in any module type for non-procedural sequences, such as a process flow of system actions.
 
-.Procedure verification
+[id="verification"]
+.Verification
 This section is optional. It provides the user with one or more steps to verify that the procedure provided the intended outcome, for example:
 
 * An example of expected command output or a pop-up window that the user receives when the procedure is successful
 * Actions for the user to complete, such as entering a command, to determine the success or failure of the procedure
 
-.Procedure additional resources
-This section is optional. The additional resources list links to other material closely related to the contents of the procedure module, such as other documentation resources, instructional videos, or labs.
+[id="troubleshooting"]
+.Troubleshooting
+This section is optional and not used often. List any actions that can help with troubleshooting the procedure. This subsection should be short. Consider whether the information might be better in a separate troubleshooting procedure or as part of a reference module that contains other troubleshooting sections.
+
+[id="next-steps"]
+.Next steps
+This section is optional. Provide links to resources that contain instructions that might be useful to the user after they complete this procedure.
+
+NOTE: Do not use *Next steps* to provide a second list of instructions.
+
+[id="additional-resources"]
+.Additional resources
+This section is optional. The listed resources link to other material closely related to the contents of the module, such as other documentation resources, instructional videos, or labs.
 
 Focus on relevant resources that might interest the user. Do not list resources for completeness. If a resource applies to all of the modules in a user story, consider listing the resource in the Additional resources section of the assembly file. If you do this, consider including the resource in the procedure module as a comment.
 
+
+
 == Additional resources
 
 * Download the link:https://github.com/redhat-documentation/modular-docs/blob/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure module template (adoc file)] for new projects.

@@ -1,5 +1,5 @@
 [id="creating-reference-modules"]
-= Creating reference modules
+= Reference modules
 
 This section explains what a reference module is and provides recommended practices for writing reference modules.
 

@@ -44,8 +44,11 @@ file3.adoc[leveloffset=+3]
 All module and assembly titles must use the H1 heading designation, such as `= My heading`.
 
 [discrete]
-== Assembly additional resources
 
-The optional additional resources list links to other material closely related to the contents of the assembly, for example, other documentation resources, instructional videos, or labs.
 
-Focus on relevant resources that might interest the user. Do not list resources for completeness.
+== Next steps and Additional resources
+These sections are optional. If you use both *Next steps* and *Additional resources*, list *Next steps* first. The listed resources link to other material closely related to the contents of the module, such as other documentation resources, instructional videos, or labs.
+
+Focus on relevant resources that might interest the user. Do not list resources for completeness. If a resource applies to all of the modules in a user story, consider listing the resource in the Additional resources section of the assembly file. If you do this, consider including the resource in the procedure module as a comment.
+
+NOTE: If you use *Next steps* or *Additional resources* in an assembly file, check whether the last module in the assembly also has *Next steps* or *Additional resources*. If so, view the rendered HTML and consider rewriting or reorganizing the assembly.
@@ -66,13 +66,18 @@ 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. Delete if not used.
-////
-* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
-* 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].
+== Next steps
+
+* This section is optional.
+* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure.
+* Use an unnumbered bullet (*) if the list includes only one step.
+
+[role="_additional-resources"]
+== Additional resources
+
+* This section is optional.
+* Provide a bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
+* Use an unnumbered bullet (*) if the list includes only one step.
 
 ////
 Restore the context to what it was before this assembly.

@@ -46,24 +46,27 @@ Delete the .Prerequisites section title and bullets if the module has no prerequ
 . Use an unnumbered bullet (*) if the procedure includes only one step.
 
 .Verification
-////
+
 Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure.
-////
-. Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful.
 
-. List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure.
+* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful.
+* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure.
+* Make each step an instruction.
+* Include one command or action per step.
+* Use an unnumbered bullet (*) if the verification includes only one step.
 
-. Make each step an instruction.
+[role="_additional-resources"]
+.Next steps
 
-. Include one command or action per step.
+* This section is optional.
+* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure.
+* Use an unnumbered bullet (*) if the list includes only one step.
 
-. Use an unnumbered bullet (*) if the verification includes only one step.
+NOTE: Do not use *Next steps* to provide a second list of instructions.
 
 [role="_additional-resources"]
 .Additional resources
-////
-Optional. Delete if not used.
-////
-* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
-* 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].
-* 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].
+
+* This section is optional.
+* Provide a bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
+* Use an unnumbered bullet (*) if the list includes only one step.