Modular Writing

In a modular approach to writing content is organized into a series of specific modules.

Contrasted with linear book-oriented or narrative writing, module- based writing results in discrete chunks of content that can be rearranged and reused in multiple documents without author intervention or rewriting.

Modular writing doesn’t include any content format formating. The format of the output is handled by a style sheet, which is applied when the content is published. The Zephyr Project uses Sphinx to build the documentation. Sphinx gathers the content from all modules and produces HTML output that allows the use of CSS stylesheets for format.

Some advantages of modular writing:

  • Write once and only once.
  • Reuse sections for multiple products, different audiences.
  • Restructure content quickly.
  • Revising a few sections is faster than revising a whole document.
  • No need to format the content.

Some terms used in modular writing:

Rules: Must do these steps.

Requirements: Must use these materials.

Guidelines: Specific things to do.

The Zephyr Project strives for full modularization of content. The modularization is still a work in progress and new content must be structured following this guidelines.

Note

The guidelines presented in basic still apply to modular writing, except where specifically noted to the contrary.

Module Types

There are four module types in modular writing: overview, concept, task, and reference. Each type answers a different question and contains distinct kinds of information. They are organized to help users find the information they need.

Overview

Main theme or goal. Overview modules set the tone and expectation for the modules that follow:

  • Present the main theme of the module group.
  • Be brief. An overview module is the container for the module group, not a detailed explanation.
  • Focus on the overall goal of the information, so the users know why it is important for them and what they will accomplish.

The Zephyr Project’s documentation uses overview modules as container modules. Container modules include a toctree directive that includes either other container modules or concept, task and reference modules. For example in a System Requirements overview module:

.. toctree::
   :maxdepth: 2

   requirements_packages.rst
   requirements_install.rst
   requirements_limitations.rst

Concept

Basic information and definitions. Effective concept modules are easy to read and easy to scan. Use these tips to write useful conceptual information:

  • Stick to one idea per module.
  • Focus on the goal for the users. Present conceptual information that supports the tasks that accomplish the goal.
  • Organize information into small chunks, and label the chunks for scannability.
  • Use bulleted lists and tables for at-a-glance access to the information.
  • Avoid referring to the module itself, as in This module describes....
  • Don’t refer to other modules, as in As you learned in the previous chapter....
  • Don’t force users to read a dense paragraph only to learn they didn’t need to read it.

Task

How to accomplish the goal. Follow these guidelines:

  • Begin each step with the goal, followed by the navigation, then the instruction. For example: “To install the package, go to the home directory and type:”
  • Write individual steps as separate, numbered entries. You can combine up to three short steps if they occur in the same part of the interface. Be mindful of the correct syntax for interfaces. For example: “Select Tools ‣ Options, and click the : guilabel:Edit tab.”
  • Limit a task to seven to ten steps if possible. Seven is ideal; ten is acceptable.
  • Break up a long task into a series of shorter tasks, collectively referred to as a process, that one must perform in sequence to achieve the goal.

Note

In a process, don’t call a task a step. Reserve the word step for a single meaningful action within a task.

  • Use a table for optional actions under a step.
  • Use the same verb for the same action.
  • Don’t put explanatory information within the task or the step; put it in a note or a paragraph after the applicable step or after the task . If the information is lengthy, put it in the associated concept module or in a container module for a group of tasks.
  • Verify that each step tells users to perform an action. Don’t force users to understand or interpret a concept while they are performing the step.

Reference

Background information. Follow these rules when writing reference modules, including modules for page-level help and command-line options:

  • For page-level reference modules, present options and their definitions in the order they appear in the interface.
  • Write the definition of an option as a sentence fragment, beginning with a third-person present-tense verb, as in Specifies..., Defines..., Creates....
  • Use “See Cross References” for cross-references to supporting tasks and concepts.

Module Structure

Each of the four different module types consists of three (sometimes four) items, in this order:

1. Title: Well-written module titles help users find information at a glance.

2. Short description: The short description answers the question “Why should I read this?”

3. Body: The body of a module is the actual content, and it includes section headings, paragraphs, tables, and lists. Use tables, lists, and figures to chunk related information. The body contains the answers to the questions “What” and “How” depending on the module type.

4. Considerations (optional): Considerations add information to some modules.

Example:

Title
#####

These tips apply to all four module types.

Sections
********
Do this...

Level 2 Sections
================

Level 3 Sections
----------------

Do this...

  • Include one idea per module.
  • Keep module titles brief and focused.
  • Put the most important and distinctive information at the beginning of the title rather than the end.
  • Create titles as sentence fragments.
  • Use plural nouns in titles, Deploying New Drivers, unless you are referring to a single item, Submitting a Change.
  • If you can take a position, use qualitative words; benefits, advantages, limitations; especially to show the benefit to the user.
  • Use “vs.”, not “versus”, in titles, Daily vs. Weekly Backups.
  • Review and rewrite the module title after you’ve written the content.

Don’t do this...

  • Don’t begin a module title with Understanding or About or How to.
  • Don’t begin a title with an article: a, an, the. Using plural nouns is one way to avoid using articles.

Module Titles

Titles of overview modules: A noun, noun phrase, or present participial form of a verb (-ing). Provides a sense of process and continuity. Examples:

  • System Requirements
  • Managing Your Network

Titles of concept modules: A descriptive noun phrase or verb phrase. The title must answer the question “What about it?” Examples:

  • Considerations When Planning a System
  • Advantages of Widget Security
  • Limitations of Edit mode

Titles of task modules: An imperative (command) phrase. Describes the task, not the function to be used. Examples:

  • Configure General Server Settings
  • Import File Formats

Titles of reference modules: The name of a reference object. Provides quick access to facts needed to understand a concept or complete a task. Examples:

  • Assembly Code Options
  • Default Values Provided by the Platform

Short Descriptions

The short description is the first paragraph of a module — a brief statement of the module’s theme that helps readers find the information they are looking for. An effective short description is:

  • Short: Provides just enough information—in one to three complete sentences or roughly 25 to 35 words to let users know whether to read more.
  • Informative: Provides enough detail for advanced users to get what they need and move on.
  • Pertinent: Doesn’t include background information; instead summarizes the purpose of the module.

Converting Conventional writing to Module-Based writing

If you are converting a conventionally written document to module- based content, you will have to rearrange and rewrite some of the content. Here are some guidelines and some things to look for:

  • Limit headings to three levels. If you are working with an older document, you might have to convert fourth and lower levels into tables or lists. Lists are excellent for splitting information up. See Lists for guidelines on creating lists.
  • Divide large concepts into smaller sections. Sections are useful when the information in each section isn’t long enough to be in its own module or when the info would not make sense in its own module. If the content has many sections, think of ways to split it into separate modules.
  • Make sure each section has an introductory paragraph. For section heads that have no introductory paragraph, add one or promote the next section up a level.
  • Keep cross-references generic. Convert explicit table and figure cross-references within the same module to generic references, such as “the following table”. Relocate these figures/tables closer to the referring text.
  • Avoid “glue text”. Glue text is a word or phrase that links a module/section to a previous or next module/section, as if the content were linear or sequential. Module-based writing is not linear.
  • Use generic terms. Instead of a specific product name, use CPU or processor or PCH when possible, especially in images. This will help repurpose the content for other products and cases.
  • Rewrite content for reusability. Search for words like chapter and page and replace with module, section, or some term that does not chain the content to the book- or page-based metaphor. When necessary, rewrite content so that it may be reused in other documents.