You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc
+18-20Lines changed: 18 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,27 +6,24 @@ See also the complementary step on the last line of this file.
6
6
7
7
ifdef::context[:parent-context: {context}]
8
8
9
+
10
+
////
11
+
Indicate the content type:
12
+
////
13
+
:_mod-docs-content-type: ASSEMBLY
14
+
9
15
////
10
16
Base the file name and the ID on the assembly title. For example:
11
17
* file name: assembly-my-user-story.adoc
12
18
* ID: [id="assembly-my-user-story_{context}"]
13
19
* Title: = My user story
14
-
////
15
-
16
-
////
17
-
Indicate the content type in one of the following
18
-
ways:
19
-
Add the prefix assembly- or assembly_ to the file name.
20
-
Add the following attribute before the module ID:
21
-
:_mod-docs-content-type: ASSEMBLY
22
-
////
23
20
24
-
////
25
21
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.
26
22
////
27
23
28
24
[id="assembly-my-user-story_{context}"]
29
25
= My user story
26
+
30
27
////
31
28
Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction.
* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure.
72
-
* Use an unnumbered bullet (*) if the list includes only one step.
67
+
* Provide information about the next steps the user might want to take. T
68
+
* This section can include text and links.
73
69
74
70
// 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.
71
+
75
72
[role="_additional-resources"]
76
73
== Additional resources
77
-
78
-
* This section is optional.
79
-
* Provide a bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
80
-
* Use an unnumbered bullet (*) if the list includes only one step.
81
-
82
74
////
83
-
Restore the context to what it was before this assembly.
75
+
Optional. Delete if not used.
76
+
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.
Base the file name and the ID on the module title. For example:
3
-
* file name: con_my-concept-module-a.adoc
4
-
* ID: [id="my-concept-module-a_{context}"]
5
-
* Title: = My concept module A
2
+
Indicate the module types:
6
3
////
7
4
8
-
////
9
-
Indicate the module type in one of the following
10
-
ways:
11
-
Add the prefix con- or con_ to the file name.
12
-
Add the following attribute before the module ID:
13
5
:_mod-docs-content-type: CONCEPT
14
-
////
15
6
16
7
////
17
-
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.
18
-
////
8
+
Base the file name and the ID on the module title. For example:
9
+
* file name: con_my-concept-module-a.adoc
10
+
* ID: [id="my-concept-module-a_{context}"]
11
+
* Title: = My concept module A
19
12
20
-
[id="my-concept-module-a_{context}"]
13
+
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.
21
14
22
-
////
23
15
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.
24
16
////
25
17
18
+
[id="my-concept-module-a_{context}"]
19
+
26
20
= My concept module A
27
21
////
28
-
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_.
22
+
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 _The IBM Style Guide_.
29
23
30
24
Be sure to include a line break between the title and the module introduction.
31
25
////
@@ -40,20 +34,19 @@ The contents of a concept module give the user descriptions and explanations nee
40
34
41
35
42
36
////
43
-
Include titles and alternative text descriptions for images.
44
-
Alternative text should provide a textual, complete description of the image as a full sentence.
37
+
Do not include level three headings (===).
38
+
Include titles and alternative text descriptions for images and enclose the descriptions in quotation marks (""). Alternative text should provide a textual, complete description of the image as a full sentence.
45
39
Images should never be the sole means of conveying information and should only supplement the text.
46
-
Avoid screenshots or other images that might quickly go out of date and that create a maintenance burden on documentation.
47
-
Provide text equivalents for every diagram, image, or other non-text element. Avoid using images of text instead of actual text.
40
+
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.
48
41
////
49
42
//.Image title
50
-
//image::image-file.png[A textual representation of the essential information conveyed by the image.]
43
+
//image::image-file.png["A textual representation of the essential information conveyed by the image."]
51
44
52
45
[role="_additional-resources"]
53
46
.Additional resources
54
47
////
55
48
Optional. Delete if not used.
49
+
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.
56
50
////
57
-
* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
58
-
* 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].
59
-
* 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].
Base the file name and the ID on the module title. For example:
3
10
* file name: proc_doing-procedure-a.adoc
4
11
* ID: [id="doing-procedure-a_{context}"]
5
12
* Title: = Doing procedure A
6
13
7
-
Indicate the module type in one of the following
8
-
ways:
9
-
Add the prefix proc- or proc_ to the file name.
10
-
Add the following attribute before the module ID:
11
-
:_mod-docs-content-type: PROCEDURE
14
+
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.
12
15
13
-
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.
16
+
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.
14
17
////
15
18
16
19
[id="doing-procedure-a_{context}"]
17
20
18
21
= Doing procedure A
19
22
////
20
23
Start the title of a procedure module with a gerund, such as Creating, Installing, or Deploying.
21
-
22
24
Be sure to include a line break between the title and the module introduction.
23
25
////
24
26
25
27
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.
26
28
27
29
.Prerequisites
28
-
29
30
* A bulleted list of conditions that must be satisfied before the user starts the steps in this module.
30
31
* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel.
32
+
* Do not use imperative statements in the Prerequisites section.
33
+
34
+
.Procedure
35
+
. Make each step an instruction.
36
+
. Include one imperative sentences for each step, for example:
37
+
.. Do this thing and then select *Next*.
38
+
.. Do this other thing, and this other thing, and then select *Next*.
39
+
. Use an unnumbered bullet (*) if the procedure includes only one step.
40
+
+
41
+
NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step the a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings cannot be converted to DITA.
31
42
32
43
////
33
-
If you have only one prerequisite, list it as a single bullet point.
34
-
Do not write prerequisites in the imperative.
35
-
You can include links to more information about the prerequisites.
36
-
Delete the .Prerequisites section title and bullets if the module has no prerequisites.
44
+
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 are only allowed in a procedure module. You can also use block headings in figure, table, and example titles.
37
45
////
38
46
39
-
.Procedure
40
47
41
-
. Make each step an instruction.
48
+
.Verification
49
+
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.
42
50
43
-
. Include one command or action for each step with the exception of simple follow-step, for example:
44
-
.. Do this thing and then select *Next*.
45
-
.. Do this other thing and then select *Next*.
51
+
* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful.
52
+
* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure.
53
+
* Make each step an instruction.
54
+
* Use an unnumbered bullet (*) if the verification includes only one step.
46
55
47
-
. Use an unnumbered bullet (*) if the procedure includes only one step.
56
+
.Troubleshooting
57
+
Delete this section if it does not apply to your module. Provide the user with troubleshooting steps.
58
+
59
+
* Make each step an instruction.
60
+
* Use an unnumbered bullet (*) if the troubleshooting includes only one step.
48
61
49
-
.Verification
62
+
63
+
.Next steps
64
+
* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure.
65
+
* Use an unnumbered bullet (*) if the list includes only one step.
50
66
51
67
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.
52
68
@@ -67,7 +83,9 @@ NOTE: Do not use *Next steps* to provide a second list of instructions.
67
83
68
84
[role="_additional-resources"]
69
85
.Additional resources
70
-
71
-
* This section is optional.
72
-
* Provide a bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
73
-
* Use an unnumbered bullet (*) if the list includes only one step.
86
+
////
87
+
Optional. Delete if not used.
88
+
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.
Base the file name and the ID on the module title. For example:
3
8
* file name: ref_my-reference-a.adoc
4
9
* ID: [id="my-reference-a_{context}"]
5
10
* Title: = My reference A
6
-
////
7
-
8
-
////
9
-
Indicate the module type in one of the following
10
-
ways:
11
-
Add the prefix ref- or ref_ to the file name.
12
-
Add the following attribute before the module ID:
13
-
:_mod-docs-content-type: REFERENCE
14
-
////
15
11
16
-
////
17
12
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.
13
+
14
+
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.
18
15
////
19
16
20
17
[id="reference-material_{context}"]
21
18
22
-
////
23
-
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.
24
-
////
25
-
26
19
= Reference material
27
20
////
28
21
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.
@@ -32,8 +25,8 @@ Be sure to include a line break between the title and the module introduction.
32
25
33
26
Write a short introductory paragraph that provides an overview of the module.
34
27
35
-
A reference module provides data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table.
36
-
A well-organized reference module enables users to scan it quickly to find the details they want.
28
+
A reference module provides data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want.
29
+
37
30
AsciiDoc markup to consider for reference data:
38
31
39
32
.Unordered list
@@ -57,7 +50,7 @@ Term 2:: Definition
57
50
.Additional resources
58
51
////
59
52
Optional. Delete if not used.
53
+
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.
60
54
////
61
-
* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros.
62
-
* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
63
-
* 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].
0 commit comments