From 8299dac33f7f0fa358a464d5b4facf49a948fbdd Mon Sep 17 00:00:00 2001 From: Rolfe Dlugy-Hegwer Date: Sun, 24 May 2020 11:40:30 -0400 Subject: [PATCH] Issue #97 prerequisites guidance --- .../content/modular-doc-manual.adoc | 2 + ...o-customers-use-modular-documentation.adoc | 24 + ...ow-do-i-use-prerequisites-in-mod-docs.adoc | 54 + ...faq-what-are-some-eppo-best-practices.adoc | 22 + modular-docs-manual/content/topics/faqs.adoc | 15 + modular-docs-manual/master.html | 2362 +++++++++++++++++ 6 files changed, 2479 insertions(+) create mode 100644 modular-docs-manual/content/topics/faq-how-do-customers-use-modular-documentation.adoc create mode 100644 modular-docs-manual/content/topics/faq-how-do-i-use-prerequisites-in-mod-docs.adoc create mode 100644 modular-docs-manual/content/topics/faq-what-are-some-eppo-best-practices.adoc create mode 100644 modular-docs-manual/content/topics/faqs.adoc create mode 100644 modular-docs-manual/master.html diff --git a/modular-docs-manual/content/modular-doc-manual.adoc b/modular-docs-manual/content/modular-doc-manual.adoc index c45292f..be4b085 100644 --- a/modular-docs-manual/content/modular-doc-manual.adoc +++ b/modular-docs-manual/content/modular-doc-manual.adoc @@ -17,3 +17,5 @@ include::topics/mod-docs-examples.adoc[leveloffset=+1] [appendix] include::topics/mod-docs-conversion.adoc[leveloffset=+1] +[appendix] +include::topics/faqs.adoc[leveloffset=+1] diff --git a/modular-docs-manual/content/topics/faq-how-do-customers-use-modular-documentation.adoc b/modular-docs-manual/content/topics/faq-how-do-customers-use-modular-documentation.adoc new file mode 100644 index 0000000..b459b32 --- /dev/null +++ b/modular-docs-manual/content/topics/faq-how-do-customers-use-modular-documentation.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// modular-docs-manual/content/topics/assy_faqs.adoc + +[id="how-do-customers-use-modular-documentation_{context}"] += How do customers use modular documentation? +//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_. + +A short introductory paragraph is required for the concept module. +It will provide an overview of the module. + +The contents of a concept module give the user descriptions and explanations needed to understand and use a product. + +* 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. + +.Additional resources + +* A bulleted list of links to other material closely related to the contents of the concept module. +* 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. +* 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]. diff --git a/modular-docs-manual/content/topics/faq-how-do-i-use-prerequisites-in-mod-docs.adoc b/modular-docs-manual/content/topics/faq-how-do-i-use-prerequisites-in-mod-docs.adoc new file mode 100644 index 0000000..824088b --- /dev/null +++ b/modular-docs-manual/content/topics/faq-how-do-i-use-prerequisites-in-mod-docs.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// modular-docs-manual/content/topics/assy_faqs.adoc + +[id="conc-qa-how-do-i-use-prerequisites-in-mod-docs_{context}"] += How do I use prerequisites in mod docs? + +.What is a prerequisite? + +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. + +.Where do I put them? + +The mod doc templates for assemblies and procedure modules both have a `.Procedures` section. + +xref:module_guidelines-assembly[] states: +> Optionally, an assembly can also include prerequisites and additional resources. +> Prerequisites are conditions that must be satisfied before the user can start following the assembly. + +Most modular documentation presents top-level assemblies as pages. So a prerequisite in a top-level assembly appears near the top of the page. + +xref:module_guidelines-procedure[] advises you: +> focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites. + +.What are some reasons to put a prerequisite in a top-level assembly? +- The prerequisite requires significant time, effort, expense, or equipment. +- You want to avoid surprising or disappointing your users when they are working through your document. +- The prerequisite belongs in multiple procedure modules. +- The prerequisite doesn't belong in any particular procedure module. + +.What are some reasons to put a prerequisite in a procedure module? +- The procedure module has a definite prerequisite. +- You believe the user can meet the prerequisite _while_ they are performing the procedure. +- 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. +- If you expect someone to reuse the module in other assemblies that don't include the prerequisite. + +.Is it okay to repeat prerequisites in assemblies and modules? +- Yes. Users often find themselves in the middle of documents and aren't aware of its other content. + +xref:module_guidelines-procedure[However, in procedure modules,]: +> focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites. + +.What about prerequisites and Every Page is Page One? + +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. + +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]. + +// .Additional resources +// +// * A bulleted list of links to other material closely related to the contents of the concept module. +// * 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. +// * 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]. diff --git a/modular-docs-manual/content/topics/faq-what-are-some-eppo-best-practices.adoc b/modular-docs-manual/content/topics/faq-what-are-some-eppo-best-practices.adoc new file mode 100644 index 0000000..f1ea1c0 --- /dev/null +++ b/modular-docs-manual/content/topics/faq-what-are-some-eppo-best-practices.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// modular-docs-manual/content/topics/assy_faqs.adoc + +[id="conc-qa-what-are-some-eppo-best-practices_{context}"] += What are some EPPO best practices? + +A short introductory paragraph is required for the concept module. +It will provide an overview of the module. + +The contents of a concept module give the user descriptions and explanations needed to understand and use a product. + +* 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. + +.Additional resources + +* A bulleted list of links to other material closely related to the contents of the concept module. +* 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. +* 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]. diff --git a/modular-docs-manual/content/topics/faqs.adoc b/modular-docs-manual/content/topics/faqs.adoc new file mode 100644 index 0000000..e4595f4 --- /dev/null +++ b/modular-docs-manual/content/topics/faqs.adoc @@ -0,0 +1,15 @@ +// This assembly is included in the following assemblies: +// +// modular-docs-manual/content/modular-doc-manual.adoc + +[id="asse-faqs"] += FAQs +:context: faqs + +You can use these FAQs to grasp significant issues raised by authors of modular documentation. +// 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. + +include::faq-how-do-i-use-prerequisites-in-mod-docs.adoc[leveloffset=+1] +include::faq-what-are-some-eppo-best-practices.adoc[leveloffset=+1] +include::faq-how-do-customers-use-modular-documentation.adoc[leveloffset=+1] +conc_qa-what-are-some-eppo-best-practices diff --git a/modular-docs-manual/master.html b/modular-docs-manual/master.html new file mode 100644 index 0000000..4dc69ea --- /dev/null +++ b/modular-docs-manual/master.html @@ -0,0 +1,2362 @@ + + + + + + + +Modular Documentation Reference Guide + + + + + +
+
+

1. Introduction

+
+
+

This manual provides instructions on how to author modularly structured documentation based on user stories. The manual defines used terminology, describes components that form modular documentation, and instructs writers on how to use provided templates to turn user stories into modular documentation.

+
+
+
+
+

2. Understanding Modular Documentation

+
+
+

This chapter explains what modular documentation is and what it is not.

+
+
+

2.1. What Modular Documentation Is

+
+

Modular documentation is documentation based on modules, which the writer combines into assemblies. An assembly can also include other assemblies.

+
+
+ + + + + +
+
Important
+		 +
+

Nesting assemblies too deep can create too much complexity, which might make the documentation difficult to use and maintain. If you are worried this might be the case, consider linking to another assembly as an alternative to direct inclusion.

+
+
+
+
+

At Red Hat, we write modular documentation that is based on user stories. This means that each assembly documents a user story.

+
+
+
+modules assemblies +
+
Figure 1. Schema of a Module and an Assembly
+
+
+
Additional Resources
+ +
+
+
+

2.2. What Modular Documentation Is Not

+
+
+
Legacy (non-modular) documentation split into small, meaningless pieces
+
+

A module must make sense and provide value on its own, even when read separately from the other modules. The templates included in this manual help ensure this.

+
+
A collection of modules that have no relationship to one another
+
+

An unorganized set of modules is confusing to users. That is why we combine modules into:

+
+
    +
  • +

    Assemblies that are based on user stories

    +
    • +
  • +

    Deliverables, like a book or help system, that present a structured view of the body of knowledge represented by a set of modules

    +
    • +
+
+
+
Always a linear, book-type model
+
+

Modular documentation is designed to enable you to deliver content flexibly. You can combine modules to build lean, article-based content or large, linear books.

+
+
+
+
+
+

2.3. A Simple Example of a Modular Guide

+
+

Download and unzip an example modular guide. The simple-mod-guide-repo directory included in the ZIP archive contains a very simple example of a modular guide with assemblies and modules. This section explains the contents of the directory.

+
+
+ + + + + +
+
Note
+		 +To build the example guide, change into the simple-mod-guide-repo directory, issue the asciidoctor master.adoc command, and open the resulting master.html file in your browser. +
+
+
+

The contents of the directory displayed in a tree-like format:

+
+
+
+
.
+├── attributes.adoc <-- File with attributes for the whole book.
+├── docs <-- Directory with assemblies and modules.
+│   ├── assembly-1.adoc <-- Assembly files with include statements for modules.
+│   ├── assembly-2.adoc
+│   └── modules
+│       ├── module-a.adoc <-- Module files.
+│       ├── module-b.adoc
+│       ├── module-c.adoc
+│       └── module-d.adoc
+└── master.adoc <-- Master file that defines the whole book.
+
+
+
+

To learn more about how a modular guide works, explore the files and directories in this example directory. For example, note that:

+
+
+
    +
  • +

    master.adoc pulls in the attribute.adoc file with AsciiDoc attributes, sets the title of the book, and pulls in the assemblies that comprise the book.

    +
    • +
  • +

    Some of the module files (in the modules directory) demonstrate how to reuse a module in multiple assemblies.

    +
    • +
  • +

    In module-b.adoc, the AsciiDoc conditional ifeval enables reusing the same module with some differences.

    +
    • +
+
+
+

Feel free to experiment with the example guide: create new assemblies and modules, reuse modules, introduce new AsciiDoc conditionals.

+
+
+
+
+
+

3. Writing Modular Documentation

+
+
+

Assemblies can include various types of modules. Use the instructions in the following sections to create modules and combine them into assemblies.

+
+
+

3.1. Creating Modules

+
+

Follow these guidelines to create different types of modules:

+
+
+ +
+
+

See Module and Assembly Examples for real-world examples of assemblies, modules, and their individual parts.

+
+
+

3.1.1. Creating Concept Modules

+
+

This section explains what a concept module is and provides recommended practices for writing concept modules.

+
+
+
Concept Module Definition
+
+

A concept module is an "understand" module. Concept modules give the user descriptions and explanations needed to understand and use a product.

+
+
+
+
Concept Module Guidelines
+
+

The core requirement for a concept module is explaining the idea, or concept. +A concept module requires a short introduction and optionally, can also include additional resources.

+
+
+

When planning a concept module, look at nouns 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 an explanation if it is not visible to users.

+
+
+
+concept diagram +
+
+
Concept Introduction
+
+

The introduction to a concept module is a single, concise paragraph that provides a short overview of the module. +A short description makes the module more usable because users can quickly determine whether the concept is useful without having to read the entire module.

+
+
+

The introduction typically answers the following questions:

+
+
+
    +
  • +

    What is the concept?

    +
    • +
  • +

    Why should the user care about the concept?

    +
    • +
+
+
Concept Body
+
+

The concept body describes the subject of the concept module.

+
+
+

Apart from paragraphs, you can use other AsciiDoc elements, such as lists, tables, or examples. +Consider including graphics or diagrams to speed up the understanding of the concept.

+
+
+

Do not include any instructions to perform an action, such as executing a command. +Action items belong in procedure modules. +See also The Six Information Types at informationmapping.com for ways to present different types of conceptual information: principle, concept, structure, process, fact.

+
+
Concept Additional Resources
+
+

The optional additional resources list links to other material closely related to the contents of the concept module, for example, other documentation resources. +Because of current tooling limitations, you cannot include xref links to other content in your collection in the concept module. +You can include xref links in the assembly that contains the concept.

+
+
+

Focus on relevant resources that are likely to be of immediate interest to the user. Do not list resources for completeness.

+
+
+
+
Additional Resources
+
+ +
+
+
+
+

3.1.2. Creating Procedure Modules

+
+

This section explains what a procedure module is and provides recommended practices for writing procedure modules.

+
+
+
Procedure Module Definition
+
+

A procedure module is a "do" module. It gives the user numbered, step-by-step instructions.

+
+
+ + + + + +
+
Important
+		 +A procedure module does not consist solely of a procedure. At the very least, the steps must be preceded by an introductory statement that provides context for the procedure. For details, see Procedure Module Guidelines. +
+
+
+
+
Procedure Module Guidelines
+
+

The required parts of a procedure module are a procedure and its introduction. Optionally, the module can also include prerequisites and additional resources.

+
+
+
+procedure diagram +
+
Figure 2. Schema of a procedure module
+
+
Procedure Introduction
+
+

The introduction is a short description of the procedure. For example, it can be a lead-in sentence or an infinitive phrase (To extract the certificate: <steps>). See also The IBM Style Guide [1] for details on introducing procedures.

+
+
+

The introduction typically provides context for the procedure, such as:

+
+
+
    +
  • +

    Who is the user performing the procedure

    +
    • +
  • +

    Why and where the user performs the procedure

    +
    • +
  • +

    Special considerations specific to the procedure

    +
    • +
+
+
+

Keep the information brief and focused on what the user needs for this specific procedure. Suggested length is 1—​3 sentences, but it can be longer.

+
+
Procedure Prerequisites
+
+

Prerequisites are conditions that must be satisfied before the user starts the procedure. If a prerequisite is a procedure or an assembly, include a link to them. See also The IBM Style Guide [1] for details on writing prerequisites.

+
+
+

Focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites.

+
+
+

Use a bulleted list for prerequisites, even if you only have a single prerequisite.

+
+
Procedure Body
+
+

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.

+
+
Procedure verification steps
+
+

This section is optional. Provide the user with one or more steps to verify that the procedure provided the intended outcome. This may consist of:

+
+
+
    +
  • +

    An example of expected command output or 'pop-up' window the user should receive when the procedure is successful.

    +
    • +
  • +

    An 'action' (or 'actions') for the user, such as running a command, to determine the success or failure of the procedure.

    +
    • +
+
+
Procedure Additional Resources
+
+

The optional additional resources list links to other material closely related to the contents of the procedure module, for example, other documentation resources, instructional videos, or labs. +Because of current tooling limitations, you cannot include xref links to other content in your collection in the procedure module. +You can include xref links in the assembly that contains the procedure.

+
+
+

Focus on relevant resources that are likely to be of immediate interest to the user. Do not list resources for completeness.

+
+
+
+
Additional Resources
+
+ +
+
+
+
+

3.1.3. Creating Reference Modules

+
+

This section explains what a reference module is and provides recommended practices for writing reference modules.

+
+
+
Reference Module Definition
+
+

Reference modules provide data that users might want to look up, but do not need to remember.

+
+
+
Example 1. Common documentation examples of reference modules
+
+
+
    +
  • +

    A list of commands that users can use with an application

    +
    • +
  • +

    A table of configuration files with definitions and usage examples

    +
    • +
  • +

    A list of default settings for a product

    +
    • +
+
+
+
+
+
Example 2. Reference modules explained using a real-life example
+
+
+

For documentation on how to cross the road, you could create these modules:

+
+
+
    +
  • +

    Concept modules:

    +
    +
      +
    • +

      What are roads

      +
      • +
    • +

      What are crossings

      +
      • +
    +
    +
    • +
  • +

    Procedure modules:

    +
    +
      +
    • +

      How to put one foot in front of another

      +
      • +
    • +

      How to use pedestrian traffic lights

      +
      • +
    • +

      How to see if the road is clear for crossing

      +
      • +
    +
    +
    • +
  • +

    Reference modules:

    +
    +
      +
    • +

      Crossing signals

      +
      • +
    • +

      Common crosswalk pavement markings

      +
      • +
    • +

      Crossing laws by country

      +
      • +
    +
    +
    • +
+
+
+
+
+
+
Reference Module Guidelines
+
+

The required part of a reference module is the reference data. +A reference module requires a short introduction.

+
+
Reference Introduction
+
+

The introduction to a reference module is a single, concise paragraph that provides a short overview of the module. A short description makes the module more usable because users can quickly determine whether the reference is useful without having to read the entire module.

+
+
Reference Body
+
+

A reference module 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.

+
+
+

To make the reference data easier to scan, organize it in a logical order (such as alphabetically) or as a table. AsciiDoc markup to consider for reference data:

+
+
+ +
+
+

If you have a large volume of the same type of information to document, use a structure into which the information details can fit, and then document each logical unit of information as one reference module. For example, think of man pages, which document very different information details, but which still use consistent titles and formats to present those details in a uniform information structure.

+
+
+
+
Additional Resources
+
+ +
+
+
+
+

3.1.4. Text Snippets or Text Fragments (Pseudo-modules)

+
+ + + + + +
+
Note
+		 +The following standard is recommended when the documentation is being maintained without a Content Management System (CMS) capable of managing complex interrelations between modules. +
+
+
+

The use of reusable text snippet files (or text fragment files) is discouraged due to the complications that can arise due to the complexity they introduce.

+
+
+

Snippet (fragment) file use should be limited to:

+
+
+
    +
  • +

    Standardized admonitions (such as 'Technology preview' and 'Beta' text).

    +
    • +
  • +

    Where there is an existing standard between the upstream and downstream communities.

    +
    • +
+
+
+
+

3.1.5. Anchor Names and File Names

+
+

To optimize modular documentation, follow these guidelines for naming module anchors and files:

+
+
+
+
Anchor names
+
+

Provide an anchor in the format [id="anchor-name_{context}"] for every module so that it can be identified by Asciidoctor when reused or cross-referenced. {context} is a variable whose value you define in the assembly. Give the anchor the same or similar name as the module heading. Separate the words in the anchor with hyphens and use an underscore to separate the {context} part:

+
+
+
+
+
[id="anchor-name_{context}"]
+= Module Heading
+
+The first sentence of the topic.
+
+
+
+
Example 1. Concept Module
+
+
[id="guided-decision-tables_{context}"]
+= Guided Decision Tables
+
+The guided decision tables feature works similarly to ...
+
+
+
+
Example 2. Procedure Module
+
+
[id="creating-guided-decision-tables_{context}"]
+= Creating Guided Decision Tables
+
+You can use guided decision tables to ...
+
+
+
+ + + + + +
+
Note
+		 +
Note on Other Anchor Formats (Not Recommended)
+
+

The format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced properly. For details, see Reusing Modules in Assemblies. Other anchor formats include [[anchor-name]] and [#anchor-name], but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.

+
+
+
+
+ + + + + +
+
Note
+		 +The underscore is recommended as the separator for {context}, because this facilitates tooling to distinguish the context part from the base anchor ID. +
+
+
+

For more information about Asciidoc anchors, see the Asciidoctor User Manual.

+
+
+
+
+
File names
+
+

Give the module file the same name as the anchor used in it (which is the same as or similar to the module heading). Assembly and module file names should accurately and closely reflect the title of the assembly or module.

+
+ + + + + +
+
Note
+		 +
+

Ensure that all members of your team use the same file naming conventions.

+
+
+
+
+
Examples
+
    +
  • +

    guided-decision-tables.adoc (Concept module)

    +
    • +
  • +

    creating-guided-decision-tables.adoc (Procedure module for creating)

    +
    • +
  • +

    editing-guided-decision-tables.adoc (Procedure module for editing)

    +
    • +
  • +

    guided-decision-table-examples.adoc (Reference module with examples)

    +
    • +
  • +

    guided-decision-table-columns.adoc (Reference module with column types)

    +
    • +
  • +

    designing-guided-decision-tables.adoc (Assembly of guided decision table modules)

    +
    • +
+
+
+
+
+
+
Additional Resources
+ +
+
+
+
+

3.2. Forming Assemblies

+
+

This section explains what an assembly is and provides recommended practices for forming assemblies.

+
+
+

3.2.1. Assembly Definition

+
+

An assembly is a collection of modules that describes how to accomplish a user story. See also Understanding Modular Documentation.

+
+
+
+

3.2.2. Assembly Guidelines

+
+

The required parts of an assembly are the introduction and modules. Optionally, an assembly can also include prerequisites and additional resources.

+
+
Assembly Introduction
+
+

The introduction explains what the user accomplishes by working through the assembled modules. It typically provides context for the assembly.

+
+
+

Consider rewording the user story to write the assembly introduction, for example:

+
+
+
    +
  • +

    User story: As an administrator, I want to provide external identity, authentication and authorization services for my Atomic Host, so that users from external identity sources can access the Atomic Host.

    +
    • +
  • +

    Assembly introduction: As a system administrator, you can use SSSD in a container to provide external identity, authentication, and authorization services for the Atomic Host system. This enables users from external identity sources to authenticate to the Atomic Host.

    +
    • +
+
+
Assembly Prerequisites
+
+

Prerequisites are conditions that must be satisfied before the user can start following the assembly.

+
+
Assembly Modules
+
+

List include files to include the required modules. Use any combination of concept, procedure, and reference modules that fulfills the purpose of the assembly.

+
+
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 are likely to be of immediate interest to the user. Do not list resources for completeness.

+
+
+
+

3.2.3. Additional Resources

+
+ +
+
+
+

3.2.4. Reusing Modules in Assemblies

+
+

When you create content in modules, you can use the same module multiple times in an assembly without having to replicate information in multiple source files. However, in order to facilitate module reuse, you must embed a document attribute variable in the anchor name for the module and then define that variable in the assembly each time the reused module appears. If the variable is not embedded and assigned, an error appears at build time reporting the duplicated anchor ID.

+
+
+
Example 3. Error at Build Time When Anchor Has No Variable
+
+
+
+
ID "$ANCHOR_NAME" is duplicated in the source content
+$BUILD_PATH fails to validate
+
+
+
+
+
+

This error is resolved by adding and defining a document variable.

+
+
+
Procedure
+
    +
  1. +

    In the module file that will be reused, add the {context} suffix with a hyphen to the anchor name in the format [id="anchor-name_{context}"].

    +
    + + + + + +
    +
    Note
    +    		 +Although you can use any document variable that clearly indicates the variable in question, such as {product} or {chapter}, the {context} variable is recommended. This variable indicates more generally that the same module can be reused in the specified "context" of one section of a document or another, regardless of whether that section is product-specific or not, whether it is a whole chapter or a small assembly, or some other limitation. +
    +
    +
    +
    Two Modules to Be Reused: Module A and Module B
    +
    +
    [id="module-A-being-reused_{context}"]
+= Module A Heading
    +
    +
    +
    +
    +
    [id="module-B-being-reused_{context}"]
+= Module B Heading
    +
    +
    +
    2. +
  2. +

    In the assembly file or the master book file, define the :context: variable immediately above any included modules that are being reused, in the format :context: variable-name. How you define the variable depends on whether the module is included once in multiple assemblies or is included multiple times in a single assembly. Note that the :context: variable definition uses hyphens to separate its terms.

    +
    +
    +
    Module Included Once in Multiple Assemblies
    +
    +

    If the reused modules are included only once in this assembly and in at least one other assembly, define an assembly-level variable such as :context: assembly-name. This indicates that the reused module is appearing in the context of that assembly.

    +
    +
    Assembly 1
    +
    +
    include::some-module-not-being-reused.adoc
+
+:context: assembly-1-name
+include::module-A-being-reused.adoc
+
+include::some-module-not-being-reused.adoc
+
+:context: assembly-1-name
+include::module-B-being-reused.adoc
    +
    +
    +
    +
    Assembly 2
    +
    +
    include::some-module-not-being-reused.adoc
+
+:context: assembly-2-name
+include::module-A-being-reused.adoc
+
+include::some-module-not-being-reused.adoc
+
+:context: assembly-2-name
+include::module-B-being-reused.adoc
    +
    +
    +
    +
    Module Included Multiple Times in a Single Assembly
    +
    +

    If a module is included multiple times in the same assembly, define a variable specific to a section or a chapter of that assembly, such as :context: section-name. This indicates that the reused module is appearing in the context of that section of the assembly.

    +
    +
    Assembly
    +
    +
    include::some-module-not-being-reused.adoc
+
+:context: section-1-name
+include::module-A-being-reused.adoc
+
+include::some-module-not-being-reused.adoc
+
+:context: section-2-name
+include::module-A-being-reused.adoc
    +
    +
    +
    +
    +
    +
    3. +
  3. +

    Return to the reused module file, and at the top of the file add a comment that identifies which assemblies the module has been added to. This helps to track reused modules in the future.

    +
    +
    +
    // Module included in the following assemblies:
+//
+// ...
+
+[id="module-A-being-reused_{context}"]
+= Module A Heading
    +
    +
    +
    4. +
+
+
+
Additional Resources
+ +
+
Practical Example 1: Reusing Modules in Multiple Assemblies
+
+

You want to reuse the "Creating Assets" procedure module and the "Projects" concept module in two assemblies: an "Asset Definitions" assembly and a "Business Rules" assembly.

+
+
+

The module files contain the following content:

+
+
+
projects.adoc
+
+
// Module included in the following assemblies:
+//
+// asset-definitions.adoc
+// business-rules.adoc
+
+[id="projects_{context}"]
+= Projects
+
+
+
+
creating-assets.adoc
+
+
// Module included in the following assemblies:
+//
+// asset-definitions.adoc
+// business-rules.adoc
+
+[id="creating-assets_{context}"]
+= Creating Assets
+
+
+
+

The assembly files contain the following content:

+
+
+
asset-definitions.adoc
+
+
include::organizational-unit.adoc
+
+include::repository.adoc
+
+:context: asset-definitions
+include::projects.adoc
+
+include::organizational-unit.adoc
+
+include::creating-packages.adoc
+
+:context: asset-definitions
+include::creating-assets.adoc
+
+include::adding-dependencies.adoc
+
+
+
+
business-rules.adoc
+
+
include::business-processes.adoc
+
+:context: business-rules
+include::projects.adoc
+
+include::project-types.adoc
+
+include::packages.adoc
+
+:context: business-rules
+include::creating-assets.adoc
+
+
+
+

For all cross-references to the reused modules, specify which context (assembly) you want to link to. For example, you can link to the "Creating Assets" procedure module as it appears either in the "Asset Definitions" assembly or in the "Business Rules" assembly. Create cross-references in the xref:anchor-name_context-variable-name[] format:

+
+
+
+
For details, see xref:creating-assets_asset-definitions[].
+
+
+
+

or

+
+
+
+
For details, see xref:creating-assets_business-rules[].
+
+
+
Practical Example 2: Reusing a Module in a Single Assembly
+
+

You want to reuse the "Projects" concept module twice in the "Business Rules" assembly.

+
+
+

The module file contains the following content:

+
+
+
projects.adoc
+
+
[id="projects_{context}"]
+= Projects
+
+
+
+

The assembly file contains the following content:

+
+
+
business-rules.adoc
+
+
:context: intro
+include::projects.adoc
+
+include::organizational-unit.adoc
+
+include::asset-types.adoc
+
+:context: asset-types
+include::projects.adoc
+
+include::dependencies.adoc
+
+
+
+

For all cross-references to the reused module, specify which context (section) you want to link to. For example, you can link to the "Projects" module as it appears either in the "Introduction" or in the "Asset Types" section. You create cross-references in the format xref:anchor-name_context-variable-name[]:

+
+
+
+
For details, see xref:projects_introduction[].
+
+
+
+

or

+
+
+
+
For details, see xref:projects_asset-types[].
+
+
+
+
+

3.2.5. Nesting Assemblies in Assemblies

+
+

When you set the :context: variable in an assembly, the variable continues to be set to the same value in the rest of the document even after the assembly itself ends. This causes problems if you include an assembly in another assembly.

+
+
+

If there is, for example, an Additional Resources section in the inner, included assembly as well as in the outer, including assembly after the include statements, the ID of the second one gets overwritten with the :context: variable of the included assembly. This causes duplicate IDs, which lead to build-time errors like:

+
+
+
+
asciidoctor: WARNING: 1.adoc: line 19: id assigned to section already in use: additional-resources-2
+
+
+
+
Example 4. Nested Assemblies with a Duplicate ID
+
+
+
+Nested Assemblies with a Duplicate ID +
+
+
+
+
+

To solve this problem, restore the :context: variable to its previous value when assemblies end:

+
+
+
    +
  1. +

    Add the following line at the top of your assemblies before :context: is defined to save the inherited context:

    +
    +
    +
    ifdef::context[:parent-context: {context}]
    +
    +
    +
    2. +
  2. +

    Add the following lines to the end of your assemblies to restore the saved context, if one already existed:

    +
    +
    +
    ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
    +
    +
    +
    3. +
+
+
+
Example 5. Correctly Nested Assemblies
+
+
+
+Correctly Nested Assemblies +
+
+
+
+
+

See also the assembly template for an example.

+
+
+
+
+
+
+

Appendix A: Modular Documentation Terms and Definitions

+
+
+
+
Assembly
+
+

A collection of several modules combined into a larger piece of text, preceded by an introduction that explains the purpose of the assembly.

+
+

The docs realization of a user story.

+
+
+
Module
+
+

An independent, self-contained chunk of information with a well-organized structure. Each module is information that a reader can understand and use by itself. A writer can use a module as a standalone article or as part of a larger body of work (an "Assembly"). A module does not depend on other documents, but it can refer the reader to other documents as additional resources. Because a module is self-contained, it must have a clear title that briefly and clearly summarizes the subject of the module. Moreover, because modules are written as context-free elements independent of other modules, they are re-usable. One module can be part of multiple assemblies. Do not include xref links in modules.

+
+
+
Concept Module
+
+

Explains a concept; for example, not action-based.

+
+
Procedure Module
+
+

Describes steps to perform an action.

+
+
Reference Module
+
+

Presents detailed reference material, for example, command syntax.

+
+
+
+
+
User Story
+
+

A short description of something the user does to achieve a goal.

+
+

Example: As an administrator, I want to set up authentication to a critical system in my infrastructure, such as a gateway VPN, or accounting system to only allow users authenticated via strong authentication methods, for example two-factor authentication.

+
+
+

As opposed to a use case, which is a description of interactions between the system and the user or other systems.

+
+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. Contrasting User Stories and Use Cases
User StoryUse Cases

Definitions:

+

A short description of something the user does to achieve a goal.

+
+

A description of interactions between the system and the user, components of the system, or the system and other systems.

+

Views the situation from:

+

The perspective of a user.

+
+

The perspective of a product and its features.

+

Focuses on:

+

The outcome as perceived by the user.

+
+

What the product does and how it does it, which includes product requirements, specification, scope.

+

Example:

+

As an office worker, I want to be able to easily switch between standing and sitting, so that I prevent back pain and other health issues associated with prolonged periods of sitting at a computer.

+
+
+ + + + + +
+
Note
+		 +This user story follows a common template for user stories in the form of "As a <type_of_user>, I want <some_goal> so that <some_reason>." +
+
+

Ergonomic work space solution - a standing desk that allows switching between standing and sitting. The standing desk:

+
+
+
    +
  • +

    Is motorized, with a button a person can press to adjust the height; the height must span up to 150 cm to be usable also by people 200 cm tall.

    +
    • +
  • +

    Is made from easy-to-clean and durable material to withstand standard office conditions, such as spilled tea or scratches: table top - polyester, legs - steel.

    +
    • +
  • +

    Has large enough work surface to comfortably fit 2 monitors, one laptop docking station, small personal items.

    +
    • +
  • +

    Can hold the weight of 100 kg, such as standard office equipment and a person sitting on the desk.

    +
    • +
  • +

    Meets safety requirements per EU standards for office equipment.

    +
    • +
  • +

    Has attractive design to fit in modern office spaces.

    +
    • +
+
+
+ + + + + +
+
Note
+		 +A use case like this can also include other ergonomic solutions, such as an adjustable sit-stand wall mount for monitors and compare their parameters, such as ease of installation, price, and ease of use. +
+
+
+ + + + + +
+
Important
+		 +
+

To fulfill their purpose, user stories must be defined based on customer needs. Therefore, they must be produced by customer-facing associates, such as product management or field teams, not by writers. Writers can only help polish the user stories if required.

+
+
+

If your team does not have user stories, do not write them yourselves. Instead, ask the stakeholders for your product to provide them to you.

+
+
+
+
+
User story-based docs
+
+

Docs developed to support a user story. For our purposes, user-story-based docs are the same as use-case-based docs.

+
+
Modular docs
+
+

Documents structured into modules and assemblies.

+
+
+
+
+ + + + + +
+
Note
+		 +We do not use the terms topic or topic-based documentation because they are too ambiguous. A topic can mean a piece of documentation, a user story, or a short chunk of content. Therefore, topic-based can mean a number of things. +
+
+
+
+
+

Appendix B: Module and Assembly Examples

+
+
+

B.1. Concept Module Examples

+
+

Available Container Images

+
+
+

How Colocation Works and Its Advantages

+
+
+

Syntax for Using qdstat

+
+
+

Standard address space

+
+
+ +
+
+
+

B.2. Procedure Module Examples

+
+

Enrolling to an Identity Management Domain Using an SSSD Container

+
+
+

Uninstalling an SSSD Container Enrolled in an Identity Management Domain

+
+
+

Purging Clusters Deployed by Ansible

+
+
+
+

B.3. Reference Module Examples

+
+

Managing Listeners

+
+
+

Changes in Ansible Variables Between Version 2 and 3

+
+
+

Example commands for retrieving address space information

+
+
+ +
+
+
+

B.4. Assembly Examples

+
+

Configuring the SSSD Container to Provide Identity and Authentication Services on Atomic Host

+
+
+

Deploying Ceph File Systems

+
+
+

Backing up an MBaaS

+
+
+
+
+
+

Appendix C: Converting to Modular Documentation

+
+
+

If you have a monolithic, feature-based manual, you can convert it to a set of modular content based on user stories. This conversion workflow involves using the customer product lifecycle to define user stories for your product, and creating the assemblies and modules necessary to fit each user story.

+
+
+

The result is documentation that is more relevant for your readers, because it is based on real-world user stories (it tells them how to accomplish their goals), and modular (it can be assembled into whatever sets and formats they might need).

+
+
+
Prerequisites
+
    +
  • +

    You should understand what modular documentation is:

    +
    + +
    +
    • +
  • +

    You should understand the benefits of modular documentation.

    +
    +

    For example, see Documentation based on user stories.

    +
    +
    • +
  • +

    Find a user story and practice documenting it as an assembly.

    +
    +

    This process of breaking down user stories into assemblies and modules is an essential element of modular documentation. You should be familiar with this process before attempting to do it for an entire feature-based book.

    +
    +
    • +
  • +

    Your repository should be set up.

    +
    +

    If you are using AsciiDoc, your repository should have a directory structure that supports modular documentation, and you should have a master.adoc file for each publication.

    +
    +
    • +
+
+
+

C.1. Overview of the Customer Product Lifecycle

+
+

User stories are the basis of modular documentation. The modular documentation conversion workflow uses the customer product lifecycle to help you discover and develop the user stories that your documentation should include.

+
+
+

While all products are different, everyone tends to use them in a similar workflow that starts with the initial research to determine which product to use, includes implementing and managing the product, and ends when the product is no longer needed. This customer product lifecycle can be broken down into phases, each of which presents unique user information requirements (that is, the user needs different types of information at each phase of the lifecycle):

+
+
+
+
Plan
+
+

What information should be gathered and what decisions should be made (for example, design/deployment) before the customer can start installing the product?

+
+
Install
+
+

How does the customer install the product on each of the supported platforms?

+
+
Configure and Verify
+
+

After the product is installed, what does the customer need to do to configure it to work in their environment? How do they test or verify that it is ready to put into production?

+
+
Develop and Test
+
+

Does the customer need to develop any custom applications to connect the product to any of their existing infrastructure?

+
+
Manage
+
+

Once the product is in production, how does the customer customize and change it on a day-to-day basis?

+
+
Monitor and Tune
+
+

Once the product is in production, how does the customer monitor its performance in order to know when changes are needed?

+
+
Upgrade and Migrate
+
+

How does the customer upgrade to newer versions of the product?

+
+
Troubleshoot
+
+

How does the customer fix common problems they may encounter?

+
+
+
+
+
+

C.2. Defining User Stories for Your Product

+
+

User stories provide the context and structure from which you can determine which assemblies and modules to create.

+
+
+

For more information about user stories, see Modular Documentation Terms and Definitions.

+
+
+

Ideally, well-defined user stories would already exist for the product you are documenting. For most writers, however, this ideal is not a reality. If you do not have any user stories from which to work, and you — as a writer — do not have all of the user information you would need to create the user stories yourself, how do you get started? This procedure provides a general approach that you can take.

+
+
+

Of course, every product differs in terms of tools, processes, team dynamics, and access to SMEs. Since you are most familiar with these aspects for your own team, you will need to adapt this general approach for your own team. Depending on your team structure, each step can be completed by either a writer or a collaboration between a writer and Content Strategist.

+
+
+
Procedure
+
    +
  1. +

    Identify the key, top-level user stories for your product.

    +
    +
    +
    +

    This step should typically be performed by the Content Strategist.

    +
    +
    +

    Start with the customer product lifecycle phases. If you have existing user stories, ask yourself which ones correspond to phases in the lifecycle. If you do not have existing user stories, create a user story for each lifecycle phase that applies to your product.

    +
    +
    +

    For more information, see Overview of the Customer Product Lifecycle.

    +
    +
    +

    For example, here is a top-level user story for the Configure and Verify phase of the customer product lifecycle:

    +
    +
    +
    Example 6. Creating Top-Level User Stories
    +
    +
    +
      +
    • +

      [Phase] Configure and Verify — [Top-level user story] As a system administrator, I want to configure PRODUCT so that it is ready for production.

      +
      • +
    +
    +
    +
    +
    +
    +
    2. +
  2. +

    Define the supporting user stories that are necessary to complete each of the top-level user stories.

    +
    +
    +
    +

    This step should typically be a collaborative effort between the Content Strategist and the writer.

    +
    +
    +

    Each top-level user story represents a "phase" of the customer lifecycle. You should go through each phase and define the user stories needed to complete the phase. You will need to use your own knowledge and expertise of the product.

    +
    +
    +

    For example, for the Configure and Verify phase, users would need to know how to configure and set up each component or feature of the product to work in their environment. You could break it down like this:

    +
    +
    +
    Example 7. Creating Second-Level User Stories
    +
    +
    +
      +
    • +

      As a system administrator, I want to configure PRODUCT so that it is ready for production.

      +
      +
        +
      • +

        As a system administrator, I want to enable PRODUCT to make and accept connections so that remote peers can exchange data with PRODUCT.

        +
        • +
      • +

        As a system administrator, I want to secure PRODUCT so that it can communicate with remote peers securely.

        +
        • +
      • +

        As a system administrator, I want to set up logging so that error conditions can be diagnosed.

        +
        • +
      +
      +
      • +
    +
    +
    +
    +
    +

    At this point, you should have a two-deep list of user stories.

    +
    +
    +
    +
    3. +
  3. +

    Go back through the list and add any additional user stories that might be needed to complete any of the secondary user stories.

    +
    +
    +
    +

    Depending on the product, one or two levels of user stories might be sufficient. For larger, more complex products, you might find yourself going multiple levels deep.

    +
    +
    +

    Be careful not to go too deep, however. At this stage, you are not defining every procedure or step needed to complete each user story. User stories represent user goals, so you should only need to go deeper if a secondary user story has multiple goals.

    +
    +
    +

    For example, under the "Configuring Product X" example in the previous step, the logging user story does not need any additional user stories — the goal cannot be reduced any further than it already is. On the other hand, the adding security settings user story might be able to go a bit deeper. Security is a goal in and of itself (users want their applications to be secure), but there are more specific goals users might have within it:

    +
    +
    +
    Example 8. Creating Additional User Stories
    +
    +
    +
      +
    • +

      As a system administrator, I want to configure PRODUCT so that it is ready for production.

      +
      +
        +
      • +

        As a system administrator, I want to enable PRODUCT to make and accept connections so that remote peers can exchange data with PRODUCT.

        +
        • +
      • +

        As a system administrator, I want to secure PRODUCT so that it can communicate with remote peers securely.

        +
        +
          +
        • +

          As a system administrator, I want to add security certificates so that clients can be authenticated.

          +
          • +
        • +

          As a system administrator, I want to use my existing LDAP configuration so that clients can be authenticated.

          +
          • +
        +
        +
        • +
      • +

        As a system administrator, I want to set up logging so that error conditions can be diagnosed.

        +
        • +
      +
      +
      • +
    +
    +
    +
    +
    +
    +
    4. +
  4. +

    For each user story in your list, define the following:

    +
    +
    +
    +
      +
    • +

      What concepts does the user need to understand to complete the user story?

      +
      +

      These will become the concept modules for the assembly.

      +
      +
      • +
    • +

      What are the procedures to complete the user story?

      +
      +

      These will become the procedure modules for the assembly.

      +
      +
      • +
    • +

      Is there any reference information that the user might want to refer to when performing this user story?

      +
      +

      These will become reference modules.

      +
      +
      • +
    +
    +
    +
    Example 9. Breaking Down User Stories
    +
    +
    +
      +
    • +

      As a system administrator, I want to configure PRODUCT so that it is ready for production.

      +
      +
        +
      • +

        As a system administrator, I want to enable PRODUCT to make and accept connections so that remote peers can exchange data with PRODUCT.

        +
        +
          +
        • +

          Concept: Types of connections

          +
          • +
        • +

          Procedure: Create "listeners" to accept incoming connections

          +
          • +
        • +

          Procedure: Create "connectors" to connect to outbound endpoints

          +
          • +
        • +

          Reference: Network connection configuration attributes

          +
          • +
        +
        +
        • +
      • +

        Additional user stories…​

        +
        • +
      +
      +
      • +
    +
    +
    +
    +
    +
    +
    5. +
+
+
+
+

C.3. Creating Assemblies

+
+

An assembly is a representation of a user story, so you need to create an assembly for each user story that you defined.

+
+
+

An assembly could represent an article, "chapter" in a book, or even an entire book. However, one of the benefits of modular documentation is that you do not need to worry about how the assembly will ultimately be used — each assembly represents a user goal, and once you create it, it can be "included" anywhere it is needed (a publication, within another assembly, and so on).

+
+
+
Procedure
+
    +
  1. +

    Create an assembly file for each user story that you identified.

    +
    +
    +
    +

    Be sure to follow the conventions for naming anchors and files. For example: guided-decision-tables.adoc

    +
    +
    +
    +
    2. +
  2. +

    For each top-level assembly file that you created, fill in the content.

    +
    +

    For more information, see Assembly Guidelines.

    +
    +
    3. +
  3. +

    Repeat the previous step for each second-level assembly.

    +
    4. +
+
+
+
+

C.4. Creating Modules

+
+

After identifying and creating the assemblies, each assembly should identify the modules that you need to create.

+
+
+
Procedure
+
    +
  1. +

    For each assembly that you created, create a module file for each module that is identified in the assembly.

    +
    +
    +
    +

    Each assembly should already have the names of the modules that should be included in the assembly. Now you just need to create the actual files for those modules.

    +
    +
    +

    Be sure to follow the conventions for naming anchors and files. For example: guided-decision-tables.adoc

    +
    +
    +
    +
    2. +
  2. +

    For each module file that you created, add content.

    +
    +
    +
    +

    Use your existing, feature-based manual to get the content. Make sure to rewrite and rework it to fit the modular documentation module templates. For more information, see:

    +
    +
    + +
    +
    +
    +
    3. +
+
+
+
+

C.5. Auditing Your Feature-Based Manual

+
+

In the process of adding content to the modules from your existing feature-based manual, it is likely that there is some existing content that did not fit into any of the user stories that you identified and thus was not pulled out. It is important to identify this content to ensure that it is no longer needed.

+
+
+
Procedure
+
    +
  1. +

    Go through your existing feature-based manual and identify any content that you did not add to an assembly or module.

    +
    2. +
  2. +

    For each piece of content that you find, determine whether it is necessary.

    +
    +
    +
    +

    If the content does not fit into a user story or assembly, then it stands to reason that it may not be necessary to complete any particular user goal. If this is the case, you should be able to discard it.

    +
    +
    +
    Example 10. Handling Extraneous Content
    +
    +
    +

    For example, many feature-based manuals contain detailed sections about how a particular feature works. This type of content, which is valuable in certain contexts, is not always necessary for user documentation — user goals generally involve doing something, not understanding how all the details work. When you encounter this type of content, ask yourself whether a user would need to understand it to accomplish any of their goals (planning, installing, configuring, managing, and so on). If the answer is no, then you can probably discard it.

    +
    +
    +
    +
    +

    On the other hand, it is also possible that the content is related to a user story that you have not considered. In that case, you should create the necessary assemblies and modules and add them to your modular doc.

    +
    +
    +
    +
    3. +
+
+
+
+
+
+

Appendix D: FAQs

+
+
+

You can use these FAQs to grasp significant issues raised by authors of modular documentation.

+
+
+

D.1. How do I use prerequisites in mod docs?

+
+

A short introductory paragraph is required for the concept module. +It will provide an overview of the module.

+
+
+

The contents of a concept module give the user descriptions and explanations needed to understand and use a product.

+
+
+
    +
  • +

    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.

    +
    • +
+
+
+
Additional resources
+
    +
  • +

    A bulleted list of links to other material closely related to the contents of the concept module.

    +
    • +
  • +

    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.

    +
    • +
  • +

    For more details on writing concept modules, see the Modular Documentation Reference Guide.

    +
    • +
  • +

    Use a consistent system for file names, IDs, and titles. For tips, see Anchor Names and File Names in Modular Documentation Reference Guide.

    +
    • +
+
+
+
+

D.2. What are some EPPO best practices?

+
+

A short introductory paragraph is required for the concept module. +It will provide an overview of the module.

+
+
+

The contents of a concept module give the user descriptions and explanations needed to understand and use a product.

+
+
+
    +
  • +

    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.

    +
    • +
+
+
+
Additional resources
+
    +
  • +

    A bulleted list of links to other material closely related to the contents of the concept module.

    +
    • +
  • +

    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.

    +
    • +
  • +

    For more details on writing concept modules, see the Modular Documentation Reference Guide.

    +
    • +
  • +

    Use a consistent system for file names, IDs, and titles. For tips, see Anchor Names and File Names in Modular Documentation Reference Guide.

    +
    • +
+
+
+
+

D.3. How do customers use modular documentation?

+
+

A short introductory paragraph is required for the concept module. +It will provide an overview of the module.

+
+
+

The contents of a concept module give the user descriptions and explanations needed to understand and use a product.

+
+
+
    +
  • +

    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.

    +
    • +
+
+
+
Additional resources
+
    +
  • +

    A bulleted list of links to other material closely related to the contents of the concept module.

    +
    • +
  • +

    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.

    +
    • +
  • +

    For more details on writing concept modules, see the Modular Documentation Reference Guide.

    +
    • +
  • +

    Use a consistent system for file names, IDs, and titles. For tips, see Anchor Names and File Names in Modular Documentation Reference Guide.

    +
    • +
+
+
+

conc_qa-what-are-some-eppo-best-practices

+
+
+
+
+
+
+
+
+1. DERESPINIS, Francis, Peter HAYWARD, Jana JENKINS, Amy LAIRD, Leslie McDONALD, Eric RADZINKSI. The IBM style guide: conventions for writers and editors. Upper Saddle River, NJ: IBM Press/Pearson, c2012. ISBN 0132101300. +
+
+ + + \ No newline at end of file