Skip to content

Update the templates to match the official ones #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 10, 2025
Merged

Update the templates to match the official ones #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 22 additions & 34 deletions templates/assembly.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,18 @@
{% if metadata -%}
:_newdoc-version: {{generator_version}}
:_template-generated: {{current_day}}
////
Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
////
:_mod-docs-content-type: ASSEMBLY
{%- endif %}

{% if !simplified -%}
////
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-of-{{module_anchor}}: {context}]
{%- endif %}

Expand All @@ -18,19 +22,11 @@ Base the file name and the ID on the assembly title. For example:
* 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 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.
////
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:
////
{% if metadata -%}
:_mod-docs-content-type: ASSEMBLY
{%- endif %}

{% if simplified -%}
[id="{{module_anchor}}"]
{%- else -%}
Expand All @@ -42,20 +38,12 @@ ifdef::context[]
endif::[]
{%- endif %}
= {{module_title}}
////
{% if !simplified -%}
Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction.

{% endif %}
If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
////

{% if !simplified -%}
:context: {{module_anchor}}

////
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: {{module_anchor}}
{%- endif %}

{% if examples -%}
Expand All @@ -75,21 +63,16 @@ 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]
////

{{include_statements}}

////
[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_PROCEDURE_doing_one_procedure.adoc[leveloffset=+2]
// Add a blank line after each 'include::' statement.

include::modules/TEMPLATE_PROCEDURE_reference-material.adoc[leveloffset=2]
////
{{include_statements}}

[role="_additional-resources"]
== Next steps

{% if examples -%}
Expand All @@ -98,14 +81,19 @@ include::modules/TEMPLATE_PROCEDURE_reference-material.adoc[leveloffset=2]
* Use an unnumbered bullet (*) if the list includes only one step.
{%- endif %}

// If the last module included in your assembly contains an Additional resources section as well, check the appearance of the rendered assembly. If the two Additional resources sections might be confusing for a reader, consider consolidating their content and removing one of them.
////
Optional. Delete if not used.

Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text.

If the last module included in your assembly contains an Additional resources section as well, check the appearance of the rendered assembly. If the two Additional resources sections might be confusing for a reader, consider consolidating their content and removing one of them.
////
[role="_additional-resources"]
== Additional resources

{% if examples -%}
* 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.
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
* xref:some-module_{context}[]
{%- endif %}

{% if !simplified -%}
Expand All @@ -114,4 +102,4 @@ Restore the context to what it was before this assembly.
////
ifdef::parent-context-of-{{module_anchor}}[:context: {parent-context-of-{{module_anchor}}}]
ifndef::parent-context-of-{{module_anchor}}[:!context:]
{%- endif %}
{%- endif %}
56 changes: 27 additions & 29 deletions templates/concept.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,32 @@
{% if metadata -%}
:_newdoc-version: {{generator_version}}
:_template-generated: {{current_day}}
////
Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
////
:_mod-docs-content-type: CONCEPT
{%- endif %}

////
Base the file name and the ID on the module title. For example:
* file name: con_my-concept-module-a.adoc
* ID: [id="my-concept-module-a_{context}"]
* Title: = My concept module A
////

////
Indicate the module type in one of the following
ways:
Add the prefix con- or con_ to the file name.
Add the following attribute before the module ID:
////
{% if metadata -%}
:_mod-docs-content-type: CONCEPT
{%- endif %}

////
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.
////
{% if simplified -%}
[id="{{module_anchor}}"]
{%- else -%}
[id="{{module_anchor}}_{context}"]
{%- endif %}
= {{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.
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_.
////

{% if examples -%}
Expand All @@ -47,23 +39,29 @@ The contents of a concept module give the user descriptions and explanations nee
* 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.
Do not include third-level headings (===).

Include titles and alternative text descriptions for images and enclose the descriptions in straight quotation marks (""). 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.

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.

Example image:

.Image title
image::image-file.png["A textual representation of the essential information conveyed by the image."]
////
//.Image title
//image::image-file.png[A textual representation of the essential information conveyed by the image.]
{%- endif %}

[role="_additional-resources"]
.Additional resources
////
Optional. Delete if not used.

Provide a bulleted list of links and display text relevant to the concept module. These links can include `link:` and `xref:` macros. Do not include additional text.
////
[role="_additional-resources"]
.Additional resources
{% if examples -%}
* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
* 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].
* 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].
{%- endif %}
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
* xref:some-module_{context}[]
{%- endif %}
66 changes: 34 additions & 32 deletions templates/procedure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
{% if metadata -%}
:_newdoc-version: {{generator_version}}
:_template-generated: {{current_day}}
////
Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
////
:_mod-docs-content-type: PROCEDURE
{%- endif %}

////
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 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.
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.

Indicate the module type in one of the following
ways:
Add the prefix proc- or proc_ to the file name.
Add the following attribute before the module ID:
////
{% if metadata -%}
:_mod-docs-content-type: PROCEDURE
{%- endif %}
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.
////
{% if simplified -%}
[id="{{module_anchor}}"]
{%- else -%}
Expand All @@ -34,59 +34,61 @@ Write a short introductory paragraph that provides an overview of the module. Th
{%- endif %}

.Prerequisites

{% if examples -%}
* 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.
* Do not use imperative statements in the Prerequisites section.
{%- endif %}

////
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.
////

.Procedure

{% if examples -%}
. Make each step an instruction.

. Include one command or action for each step with the exception of simple follow-step, for example:
. Include one imperative sentence for each step, for example:
.. Do this thing and then select *Next*.
.. Do this other thing and then select *Next*.

.. Do this other thing, and this other thing, and then select *Next*.
. Use an unnumbered bullet (*) if the procedure includes only one step.
+
NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA.
{%- endif %}

////
Only the following block headings can be reliably mapped to DITA: Prerequisites, Procedure, Verification, Troubleshooting, Troubleshooting steps, Next steps, Next step, Additional resources. They must appear in this order and, with the exception of Additional resources, are only allowed in a procedure module. You can also use block headings in figure, table, and example titles.
////
.Verification

{% if examples -%}
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.
* Make each step an instruction.
* Include one command or action per step.
* Use an unnumbered bullet (*) if the verification includes only one step.
{%- endif %}

[role="_additional-resources"]
.Next steps
.Troubleshooting
{% if examples -%}
Delete this section if it does not apply to your module. Provide the user with troubleshooting steps.

* Make each step an instruction.
* Use an unnumbered bullet (*) if the troubleshooting includes only one step.
{%- endif %}

.Next steps
{% if examples -%}
* This section is optional.
* Delete this section if it does not apply to your module.
* 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.

NOTE: Do not use *Next steps* to provide a second list of instructions.
{%- endif %}

////
Optional. Delete if not used.

Provide a bulleted list of links and display text relevant to the procedure module. These links can include `link:` and `xref:` macros. Do not include additional text.
////
[role="_additional-resources"]
.Additional resources

{% if examples -%}
* 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.
{%- endif %}
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
* xref:some-module_{context}[]
{%- endif %}
Loading