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.

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 required part of a procedure module is the concept explanation. Optionally, the module can also include an introduction and 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 explanation if it is not visible to users.

concept diagram
Writing the 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 I care about the concept?

Writing the Concept Explanation

The concept explanation 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.

Writing Additional Resources

Additional resources list links to other material closely related to the contents of the procedure module: other documentation resources (such as assemblies or modules), instructional videos, labs, and similar resources.

Focus on relevant resources that are likely to be of immediate interest to the user. Do not list every resource that could conceivably be related.

Related Information

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 introduction statement that provides context for the procedure. For details, see Writing the Introduction.
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
Writing the 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.

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

Writing the Procedure

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.

Writing Additional Resources

Additional resources list links to other material closely related to the contents of the procedure module: other documentation resources (such as assemblies or modules), instructional videos, labs, and similar resources.

Focus on relevant resources that are likely to be of immediate interest to the user. Do not list every resource that could conceivably be related.

Additional Resources

3.1.3. Reference Module Guidelines

A reference module lists things, such as a list of commands, or has a very regimented structure, such as the consistent structure of man pages. A reference module explains the details that a customer needs to know to do a procedure. A reference module is well-organized if users can scan it quickly to find the details they want.

  • A reference module that is a list of things may be made easier to scan if its content is organized alphabetically or formatted as a table. Think of an alphabetical list of commands that can be used with an application, or of an alphabetical list of system components with brief definitions formatted as a 2-column table.

  • If you have a large volume of the same type of information to document, figure out a consistent structure into which the information details can fit, and then doument 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 consistent information structure.

Related information

Download the reference module template for new projects.

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.

Writing the Introduction

The introduction explains what the user will accomplish 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.

Writing Prerequisites

Prerequisites are conditions that must be satisfied before the user can start following the assembly. For details, see Writing Prerequisites.

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

Adding Additional Resources

Additional resources list links to other material closely related to the contents of the assembly: other documentation resources (such as assemblies or modules), instructional videos, labs, and similar resources.

Focus on relevant resources that are likely to be of immediate interest to the user. Do not list every resource that could conceivably be related.

3.2.3. Additional Resources

3.3. Additional Resources

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

A building block of information with a well-organized structure.

Because modules are written as context-free elements independent of other modules, they are re-usable: one module can be part of multiple assemblies.

Concept Module

Explains a concept; i.e. 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 (gateway VPN, accounting system) to only allow users authenticated via strong authentication methods (two-factor authentication).

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

For details, see User Stories and Use Cases: What’s the Difference? in Mojo.

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

Docs 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

Example 1. Concept Module: How Ceph Works with Satellite 5

CONCEPT TITLE

How Ceph Works with Satellite 5

CONCEPT EXPLANATION

When a Red Hat Ceph Storage node is connected to a Red Hat Satellite 5 Server, the server hosts package repositories and provides system updates.

Once you register the Red Hat Ceph Storage nodes with the Satellite 5 server, you can deliver upgrades to the Ceph cluster without allowing a direct connection to the Internet, as well as search and view errata applicable to the cluster nodes.

RELATED INFORMATION

N/A

Example 2. Concept Module Example: What a Database Contains

CONCEPT TITLE

What a Database Contains

CONCEPT EXPLANATION

Every database consists of:

  • Data

  • Schema: a specification of structure of the data

For example, an online store might contain such data: user names, their passwords, products they bought, and how many products remain in the store.

This data is organized using a schema that might be represented by three tables, each containing:

  • User names and their corresponding passwords

  • User names and the list of products they bought

  • Products available in the store and their quantities

RELATED INFORMATION

N/A

Example 3. Concept Module Example: Types of Groups in Identity Management

CONCEPT TITLE

Types of Groups in Identity Management

CONCEPT EXPLANATION

POSIX groups (the default)

Groups that support POSIX attributes for their members.

Non-POSIX groups

Groups whose group members must belong to the IdM domain.

External groups

Groups that support adding group members who exist in an identity store outside of the IdM domain. The external store can be a local system, an Active Directory domain, or a directory service.

RELATED INFORMATION

N/A

B.2. Procedure Module Examples

Example 4. Procedure Module: Installing Third-Party Certificates for HTTP or LDAP

PROCEDURE TITLE

Installing Third-Party Certificates for HTTP or LDAP

PURPOSE

Installing a new SSL server certificate for the Apache Web Server, the Directory Server, or both replaces the current SSL certificate with a new one.

PREREQUISITES

  • To install the certificate, you need your private SSL key (ssl.key in the procedure below) and your SSL certificate (ssl.crt in the procedure below).

    For a list of accepted formats of the key and certificate, see the ipa-server-certinstall(1) man page.

  • The ssl.crt certificate must be signed by a certificate authority (CA) known by the service you are loading the certificate into.

    If this is not the case, install the CA certificate of the CA that signed ssl.crt into IdM, as described in Section 34.3, “Installing a CA Certificate Manually”.

STEPS

  1. Use the ipa-server-certinstall utility to install the certificate.

    For example, to install the SSL certificate into the Apache Web Server (--http) as well as the Directory Server (--dirsrv):

    # ipa-server-certinstall --http --dirsrv ssl.key ssl.crt

  2. Restart the server into which you installed the certificate.

    To restart the Apache Web Server:

    # systemctl restart httpd.service

    To restart the Directory Server:

    # systemctl restart dirsrv@REALM.service

  3. To verify that the certificate has been correctly installed, make sure it is present in the certificate database.

    To display the Apache certificate database:

    # certutil -L -d /etc/httpd/alias

    To display the Directory Server certificate database:

    # certutil -L -d /etc/dirsrv/slapd-REALM/

RELATED INFORMATION

N/A

Example 5. Procedure Module: Raising the Domain Level

PROCEDURE TITLE

Raising the Domain Level

PURPOSE

Important
 This is a non-reversible operation. If you raise the domain level from 0 to 1, you cannot downgrade from 1 to 0 again.

PREREQUISITES

N/A

STEPS

  1. Log in as the administrator:

    $ kinit admin

  2. Run the ipa domainlevel-set command and provide the required level:

    $ ipa domainlevel-set 1
-----------------------
Current domain level: 1
-----------------------

RELATED INFORMATION

N/A

Example 6. Procedure Module (Troubleshooting): External Certificate Authority Installation Fails

PROCEDURE TITLE

External Certificate Authority Installation Fails

PURPOSE

The ipa-server-install --external-ca command fails with the following error:

ipa         : CRITICAL failed to configure ca instance Command '/usr/sbin/pkispawn -s CA -f /tmp/configuration_file' returned non-zero exit status 1
Configuration of CA failed

The env\|grep proxy command displays variables such as the following:

http_proxy=http://example.com:8080
ftp_proxy=http://example.com:8080
https_proxy=http://example.com:8080

What this means:

The *_proxy environmental variables are preventing the server from being installed.

PREREQUISITES

N/A

STEPS

To fix the problem:

  1. Use the following shell script to unset the *_proxy environmental variables:

    # for i in ftp http https; do unset ${i}_proxy; done

  2. Run the pkidestroy utility to remove the unsuccessful CA subsystem installation:

    # pkidestroy -s CA -i pki-tomcat; rm -rf /var/log/pki/pki-tomcat  /etc/sysconfig/pki-tomcat  /etc/sysconfig/pki/tomcat/pki-tomcat  /var/lib/pki/pki-tomcat  /etc/pki/pki-tomcat /root/ipa.csr

  3. Remove the failed IdM server installation:

    # ipa-server-install --uninstall

  4. Retry running the ipa-server-install --external-ca command.

RELATED INFORMATION

N/A

Example 7. Procedure Module (Troubleshooting): All Monitors Failed to Start Because of a Corrupted Store

PROCEDURE TITLE

All Monitors Failed to Start Because of a Corrupted Store

PURPOSE

All Ceph Monitors terminated unexpectedly or failed to start. In addition, one or both of the following error messages are logged to the monitor log:

Corruption: error in middle of record
Corruption: 1 missing files; e.g.: /var/lib/ceph/mon/mon.0/store.db/1234567.ldb

What this means:

Ceph Monitors store the cluster map in a key-value store such as LevelDB. If the store is corrupted on a Monitor, the Monitor terminates unexpectedly and fails to start again.

Production clusters must use at least three Monitors, so that if one Monitor fails, it can be replaced with a new one. However, under certain circumstances, all Monitors can have corrupted stores. For example, when the Monitor nodes have improperly configured disk or file system settings, the underlying file system can be corrupted after a power outage.

PREREQUISITES

N/A

STEPS

To fix the problem:

If the store is corrupted on all Monitors, you can recover it with the information stored on the Object Storage Device (OSD) nodes by using utilities called ceph-monstore-tool and ceph-objectstore-tool.

Before you start:

  • Ensure that you have the rsync utility installed.

Run the following commands from the Monitor node with the corrupted store:

  1. (…​)

  2. (…​)

  3. (…​)

RELATED INFORMATION

Additional Resources

  • See Installing Ceph Ansible for details.

B.3. Assembly Examples

Example 8. Assembly Example: Backing up an MBaaS

ASSEMBLY TITLE

Backing up an MBaaS

PURPOSE OF THE ASSEMBLY

You can back up an MBaas by following this procedure. After completing the procedure and storing the backup data safely, you can restore an MBaaS to the state at the time of backup.

PREREQUISITES

Requirements

  • A self-managed MBaaS installation on an OpenShift platform

  • A local installation of the oc binary

  • The oc binary has a logged in user on the platform you wish to back up

  • The oc binary has a logged in user with permission to run the oc get pc command

CONCEPT MODULE(S)

Expected Storage Requirements

(…​)

What Data is Backed Up

(…​)

PROCEDURE MODULE(S)

Backing up the MongoDB Data

(…​)

Backing up the Nagios Data

(…​)

RELATED INFORMATION

N/A

Example 9. Assembly Example: Tuning Provisioning of a Large Number of Entries

ASSEMBLY TITLE

Tuning Provisioning of a Large Number of Entries

PURPOSE OF THE ASSEMBLY

Adding a large number of entries using the usual workflow can be very slow. This chapter describes how to tune the process to ensure the provisioning is completed as quickly as possible.

As part of the procedure:

  • Identity Management reads entries to be provisioned from an LDIF file and then imports them to the target Identity Management LDAP instance.

  • The administrator sets custom values for certain attributes, such as cache sizes, and disables the MemberOf and Schema Compatibility plug-ins. The procedure includes running the fixup-memberof.pl plug-in on the provisioned entries to compensate for disabling MemberOf.

This procedure has been designed and tested to provision the following entry types: user, user group, host, host group, sudo rules, and host-based access control rules.

PREREQUISITES

Recommendations and Prerequisites

Recommendations:

  • When provisioning a large number of entries (10,000 or more), do not allow any LDAP client to access the server on which the entries are provisioned or to rely on the information from the server. For example, you can achieve this by disabling ports 389 and 636 on the server and using LDAPI to work over Unix sockets.

    Reason: The MemberOf plug-in is disabled on the server, which means that membership information on the server is not valid.

  • Stop applications that are not required to be running during the provisioning.

    Reason: This helps free as much memory on the machine as possible. The free memory will be used by the file system cache, thus improving the performance of the provisioning.

  • Run the procedure on a fresh IdM deployment with only one server. Create replicas only after the provisioning has been completed.

    Reason: The provisioning throughput is much faster than replication. In a deployment with more that one server, information on the replicas would become significantly outdated.

Prerequisites:

  • Generate an LDIF file containing the entries you want to provision. For example, if you are migrating an existing IdM deployment, create the LDIF file by exporting all the entries using the ldapsearch utility.

CONCEPT MODULE(S)

N/A

PROCEDURE MODULE(S)

Backing up the Current DS Tuning Parameter Values

(…​)

Adjusting the Database, Domain Entry, and DN Cache Size

(…​)

Disabling Unnecessary Services and Adjusting Database Locks

(…​)

Importing the Entries

(…​)

Re-enabling the Disabled Services and Restoring the Original Attribute Values

(…​)

RELATED INFORMATION

N/A

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.