Update the modular templates to the latest upstream version

Author: Marek Suchánek

templates/assembly.adoc

@@ -16,7 +16,7 @@ The ID is an anchor that links to the module. Avoid changing it after the module
 ////
 
 ////
-Indicate the module type in one of the following
+Indicate the content type in one of the following
 ways:
 Add the prefix assembly- or assembly_ to the file name.
 Add the following attribute before the module ID:
@@ -31,6 +31,8 @@ ifdef::context[]
 endif::[]
 = {{module_title}}
 ////
+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.
 ////
 
@@ -66,6 +68,7 @@ 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.
 
 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]
 ////

templates/concept.adoc

@@ -23,6 +23,8 @@ The `context` attribute enables module reuse. Every module ID includes {context}
 = {{module_title}}
 ////
 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_.
+
+Be sure to include a line break between the title and the module introduction.
 ////
 
 {% if examples -%}
@@ -32,7 +34,17 @@ The contents of a concept module give the user descriptions and explanations nee
 
 * Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
 * Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
-* Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
+* Avoid including action items. Action items belong in procedure modules. However, in some cases a concept or reference can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund.
+
+////
+Include titles and alternative text descriptions for images.
+Alternative text should provide a textual, complete description of the image as a full sentence.
+Images should never be the sole means of conveying information and should only supplement the text.
+Avoid screenshots or other images that might quickly go out of date and that create a maintenance burden on documentation.
+Provide text equivalents for every diagram, image, or other non-text element. Avoid using images of text instead of actual text.
+////
+.Image title
+image::image-file.png[A textual representation of the essential information conveyed by the image.]
 {%- endif %}
 
 [role="_additional-resources"]

templates/procedure.adoc

@@ -4,12 +4,8 @@ Base the file name and the ID on the module title. For example:
 * ID: [id="proc-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.
+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. The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in an assembly file.
 
-The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
-////
-
-////
 Indicate the module type in one of the following
 ways:
 Add the prefix proc- or proc_ to the file name.
@@ -20,27 +16,31 @@ Add the following attribute before the module ID:
 [id="{{module_id}}_{context}"]
 = {{module_title}}
 ////
-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 gerund, such as Creating, Installing, or Deploying.
 ////
 
 {% if examples -%}
-Write a short introductory paragraph that provides an overview of the module.
-
-Procedure modules should include the steps that users perform and address user motivation.
+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.
 {%- endif %}
 
 .Prerequisites
 
 {% if examples -%}
-* A bulleted list of conditions that must be satisfied before the user starts following this module.
-* You can also link to other modules or assemblies the user must follow before starting this module.
-* Delete the section title and bullets if the module has no prerequisites.
+* A bulleted list of conditions that must be satisfied before the user starts the steps in this module.
+* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel.
+
+////
+If you have only one prerequisite, list it as a single bullet point.
+Do not write prerequisites in the imperative.
+You can include links to more information about the prerequisites.
+Delete the .Prerequisites section title and bullets if the module has no prerequisites.
+////
 {%- endif %}
 
 .Procedure
 
 {% if examples -%}
-. Start each step with an active verb.
+. Make each step an instruction.
 
 . Include one command or action for each step with the exception of simple follow-step, for example:
 .. Do this thing and then select *Next*.
@@ -55,14 +55,17 @@ Delete this section if it does not apply to your module. Provide the user with v
 ////
 
 {% if examples -%}
-. Start each step with an active verb.
+. 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 procedure includes only one step.
+. Use an unnumbered bullet (*) if the verification includes only one step.
 {%- endif %}
 
-
 [role="_additional-resources"]
 .Additional resources
 ////

templates/reference.adoc

@@ -21,6 +21,8 @@ Add the following attribute before the module ID:
 = {{module_title}}
 ////
 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.
 ////
 
 {% if examples -%}