Skip to content

Commit 8299dac

Browse files
rolfedhrolfedh
committed
Issue #97 prerequisites guidance
1 parent c6865c6 commit 8299dac

File tree

6 files changed

+2479
-0
lines changed

6 files changed

+2479
-0
lines changed

‎modular-docs-manual/content/modular-doc-manual.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,5 @@ include::topics/mod-docs-examples.adoc[leveloffset=+1]
1717
[appendix]
1818
include::topics/mod-docs-conversion.adoc[leveloffset=+1]
1919

20+
[appendix]
21+
include::topics/faqs.adoc[leveloffset=+1]

‎modular-docs-manual/content/topics/faq-how-do-customers-use-modular-documentation.adoc

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Module included in the following assemblies:
2+
//
3+
// modular-docs-manual/content/topics/assy_faqs.adoc
4+
5+
[id="how-do-customers-use-modular-documentation_{context}"]
6+
= How do customers use modular documentation?
7+
//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.
8+
//Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_.
9+
10+
A short introductory paragraph is required for the concept module.
11+
It will provide an overview of the module.
12+
13+
The contents of a concept module give the user descriptions and explanations needed to understand and use a product.
14+
15+
* Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
16+
* 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.
17+
* Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
18+
19+
.Additional resources
20+
21+
* A bulleted list of links to other material closely related to the contents of the concept module.
22+
* Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
23+
* 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].
24+
* 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].

‎modular-docs-manual/content/topics/faq-how-do-i-use-prerequisites-in-mod-docs.adoc

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// Module included in the following assemblies:
2+
//
3+
// modular-docs-manual/content/topics/assy_faqs.adoc
4+
5+
[id="conc-qa-how-do-i-use-prerequisites-in-mod-docs_{context}"]
6+
= How do I use prerequisites in mod docs?
7+
8+
.What is a prerequisite?
9+
10+
Prerequisites are requirements the user or their environment must meet before starting a procedure. A prerequisite can be a _thing_, such as a software version, or an _action_, such as a configuration task.
11+
12+
.Where do I put them?
13+
14+
The mod doc templates for assemblies and procedure modules both have a `.Procedures` section.
15+
16+
xref:module_guidelines-assembly[] states:
17+
> Optionally, an assembly can also include prerequisites and additional resources.
18+
> Prerequisites are conditions that must be satisfied before the user can start following the assembly.
19+
20+
Most modular documentation presents top-level assemblies as pages. So a prerequisite in a top-level assembly appears near the top of the page.
21+
22+
xref:module_guidelines-procedure[] advises you:
23+
> focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites.
24+
25+
.What are some reasons to put a prerequisite in a top-level assembly?
26+
- The prerequisite requires significant time, effort, expense, or equipment.
27+
- You want to avoid surprising or disappointing your users when they are working through your document.
28+
- The prerequisite belongs in multiple procedure modules.
29+
- The prerequisite doesn't belong in any particular procedure module.
30+
31+
.What are some reasons to put a prerequisite in a procedure module?
32+
- The procedure module has a definite prerequisite.
33+
- You believe the user can meet the prerequisite _while_ they are performing the procedure.
34+
- If the assembly is long and is xref:faq-how-do-customers-use-documentation[the user is likely to miss seeing the prerequisite] or to forget about it.
35+
- If you expect someone to reuse the module in other assemblies that don't include the prerequisite.
36+
37+
.Is it okay to repeat prerequisites in assemblies and modules?
38+
- Yes. Users often find themselves in the middle of documents and aren't aware of its other content.
39+
40+
xref:module_guidelines-procedure[However, in procedure modules,]:
41+
> focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites.
42+
43+
.What about prerequisites and Every Page is Page One?
44+
45+
Mark Baker's [_Every Page is Page One_ (EPPO)] is an influential book in the field of technical communications. This [_Modular Documentation Reference Guide_ (MDRG)](https://redhat-documentation.github.io/modular-docs/) and EPPO are both based on the principles of minimalism in technical communications pioneered in John Carroll's _The Nurnberg Funnel_. This guide, MDRG, does not explicitly address EPPO.
46+
47+
That said, Mark Baker has an interesting blog post called link:https://everypageispageone.com/2014/07/14/there-are-no-prerequisites/[There are no Prerequisites].
48+
49+
// .Additional resources
50+
//
51+
// * A bulleted list of links to other material closely related to the contents of the concept module.
52+
// * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
53+
// * 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].
54+
// * 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].

‎modular-docs-manual/content/topics/faq-what-are-some-eppo-best-practices.adoc

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Module included in the following assemblies:
2+
//
3+
// modular-docs-manual/content/topics/assy_faqs.adoc
4+
5+
[id="conc-qa-what-are-some-eppo-best-practices_{context}"]
6+
= What are some EPPO best practices?
7+
8+
A short introductory paragraph is required for the concept module.
9+
It will provide an overview of the module.
10+
11+
The contents of a concept module give the user descriptions and explanations needed to understand and use a product.
12+
13+
* Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
14+
* 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.
15+
* Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
16+
17+
.Additional resources
18+
19+
* A bulleted list of links to other material closely related to the contents of the concept module.
20+
* Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
21+
* 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].
22+
* 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].

‎modular-docs-manual/content/topics/faqs.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// This assembly is included in the following assemblies:
2+
//
3+
// modular-docs-manual/content/modular-doc-manual.adoc
4+
5+
[id="asse-faqs"]
6+
= FAQs
7+
:context: faqs
8+
9+
You can use these FAQs to grasp significant issues raised by authors of modular documentation.
10+
// Use this assembly to introduce topics that are adjacent to the predominantly linear organization of the MDRG guide. For example, this guide's modules on assemblies and procedure modules both discuss prerequisites. This FAQ contains a discussion of prerequisites that discusses prerequisites in general and references both modules.
11+
12+
include::faq-how-do-i-use-prerequisites-in-mod-docs.adoc[leveloffset=+1]
13+
include::faq-what-are-some-eppo-best-practices.adoc[leveloffset=+1]
14+
include::faq-how-do-customers-use-modular-documentation.adoc[leveloffset=+1]
15+
conc_qa-what-are-some-eppo-best-practices

0 commit comments

Comments
 (0)