Documenting modules

Document any module you write, whether your module is for internal use only or for publication on the Forge. Complete, clear documentation helps your module users understand what your module can do and how to use it.

Write your module usage documentation in Markdown, in a README based on our module README template. Use Puppet Strings to generate reference information for your module's classes, defined types, functions, tasks, task plans, and resource types and providers.

Use clear and consistent language in your Module documentation. It should be easy to read both on the web and in the terminal. Whether you are writing your README or code comments for Puppet Strings docs generation, following some basic formatting guidelines and best writing practices can help make your module documentation great.

Documentation best practices

If you want your documentation to really shine, a few best practices can help make your documentation clear and readable.

  • Use the second person; that is, write directly to the person reading your document. For example, “If you’re installing the cat module on Windows....”

  • Use the imperative; that is, directly tell the user what they must do. For example, "Secure your dog door before installing the cat module."

  • Use the active voice whenever possible. For example, "Install the cat and bird modules on separate instances" rather than "The cat and bird modules should be installed on separate instances."

  • Use the present tense, almost always. Events that regularly occur should be present tense: "This parameter sets your cat to 'purebred'. The purebred cat alerts you for breakfast at 6 a.m." Use future tense only when you are specifically referring to something that takes place at a time in the future, such as "The `tail` parameter is deprecated and will be removed in a future version. Use `manx` instead."

  • Avoid subjective words. For example, don't write "It's quick and easy to teach an old cat new tricks." Subjective words like "quick" and "easy" can frustrate and even alienate a reader who finds teaching a cat difficult or time-consuming.

  • Lists, whether ordered or unordered, make things clearer for the reader. When you're writing about steps that happen in a sequence, use an ordered list (1, 2, 3…). If order doesn’t matter, like in a list of options or requirements, use an unordered (bulleted) list.

Writing the module README

In your README, include basic module information and extended usage examples for the most common use cases.

Your README tells users what your module does and how they can use it. Include reference information as a separate REFERENCE.md file in the module's root directory.

Important: The Reference section of the README is deprecated.Puppet Strings generates a REFERENCE.md file containing all the reference information for your module, including a complete list of your module's classes, defined types, functions, resource types and providers, Puppet tasks and plans, along with parameters for each. See the topic about creating reference documentation for details.

Write your README in Markdown and use the .md or .markdown extension for the file. If you used Puppet Development Kit (PDK), you already have a copy of the README template in .md format in your module. For more information about Markdown usage, see the Commonmark reference.

Use the following sections in your README:

Description
What the module does and why it is useful.
Setup
Prerequisites for module use and getting started information.
Usage
Instructions and examples for common use cases or advanced configuration options.
Reference
If the module contains facts or type aliases, include them in a short supplementary reference section. All other reference information, such as classes and their parameters, are in the REFERENCE.md file generated by Strings.
Limitations
OS compatibility and known issues.
Development
Guide for contributing to the module.

Table of contents

The table of contents helps your users find their way around your module README.

Start with the module name as a Level 1 heading at the top of the module, followed by "Table of Contents" as a Level 4 heading. Under the table of contents heading, include a numbered list of top-level sections, with any necessary subsections in a bulleted list below the section heading. Link each section to its corresponding heading in the README. 

# modulename

#### Table of Contents

1. [Module Description - What the module does and why it is useful](#module-description)
1. [Setup - The basics of getting started with [modulename]](#setup)
   * [What [modulename] affects](#what-[modulename]-affects)
   * [Setup requirements](#setup-requirements)
   * [Beginning with [modulename]](#beginning-with-[modulename])
1. [Usage - Configuration options and additional functionality](#usage)
1. [Limitations - OS compatibility, etc.](#limitations)
1. [Development - Guide for contributing to the module](#development)

Module description

In your module description, briefly tell users why they might want to use your module. Explain what your module does and what kind of problems users can solve with it.

The short description helps the user decide if your module is what they want. What are the most common use cases for your module? Does your module just install software? Does it install and configure it? Give your user information about what to expect from the module. 

## Module description

The `cat` module installs, configures, and maintains your cat in both apartment and residential house settings.

The cat module automates the installation of a cat to your apartment or house, and then provides options for configuring the cat to fit your environment's needs. After it's installed and configured, the cat module automates maintenance of your cat through a series of resource types and providers.

Setup section

In the setup section, detail how your user can successfully get your module functioning. Include requirements, steps to get started, and any other information users might need to know before they start using your module.

Module installation instructions are covered both on the module's Forge page and in the Puppet docs, so don't reiterate them here. In this section, include the following subsections, as applicable:

What <modulename> affects

Include this section only if:

  • The module alters, overwrites, or otherwise touches files, packages, services, or operations other than the named software; OR

  • The module's general performance can overwrite, purge, or otherwise remove entries, files, or directories in a user's environment. For example: 
    ## Setup

### What cat affects

* Your dog door might be overwritten if not secured before installation.
Setup requiremements
Include this section only if the module requires additional software or some tweak to a user's environment. For instance, the puppetlabs-firewall module uses Ruby-based providers which required pluginsync to be enabled.
Beginning with <modulename>
Always include this section to explain the minimum steps required to get the module up and running in a user's environment. You can use basic proof of concept use cases here; it doesn't have to be something you would run in production. For simple modules, "Declare the main `::cat` class" is enough.

Usage section

Include examples for common use cases in the usage section. Provide usage information and code examples to show your users how to use your module to solve problems.

If there are many use cases for your module, include three to five examples of the most important or common tasks a user can accomplish. The usage section is a good place to include more complex examples that involve different types, classes, and functions working together. For example, the usage section for the puppetlabs-apache module includes an example for setting up a virtual host with SSL, which involves several classes. 

## Usage

You can manage all interaction with your cat through the main `cat` class. With the default options, the module installs a basic cat with no optimizations.

### I just want cat, what's the minimum I need?

```
include '::cat'
```

### I want to configure my lasers

Use the following to configure your lasers for a random-pattern, 20-minute playtime at 3 a.m. local time.

```
    class { 'cat':
      laser => {
        pattern    => 'random',
        duration   => '20',
        start_time => '0300',
      }
    }
```

Limitations section

In the limitations section, list any incompatibilities, known issues, or other warnings. 

## Limitations

This module cannot be used with the smallchild module.

Development section

In the development section, tell other users the ground rules for contributing to your project and explain how they should submit their work.

Creating reference documentation

List reference information --- a complete list of classes, defined types, functions, resource types and providers, tasks, and plans --- in a separate REFERENCE.md file in the root directory of your module.

Use Puppet Strings to generate this documentation based on your comments and module code. If you aren't yet using Strings to generate documentation, you can manually create a REFERENCE.md file.

Tip: Previously, we recommended that module authors include reference information in the README itself. However, the reference section often became quite long and difficult to maintain. Moving reference information to a separate file keeps the README more readable, and using Strings to generate this file makes it easier to maintain.

The Forge displays information from a module's REFERENCE.md file in a reference tab on the module's detail page, so the information remains easily accessible to users. To create a REFERENCE.md file for your module, add Strings comments to the code for each of your classes, defined types, functions, task plans, and resource types and providers, and then run Strings to generate documentation in Markdown. You can create a REFERENCE.md file manually, but remember that if you then generate a REFERENCE.md with Strings, it overwrites any existing REFERENCE.md file.

For details on adding comments to your code, see the Strings style guide. For instructions on how to install and use Strings, see the topics about Puppet Strings.

Manually writing reference documentation

If you aren't using Strings yet to generate your reference documentation, you can manually create a REFERENCE.md file listing each of your classes, defined types, resource types and providers, functions, and facts, along with any parameters.

To manually document reference information, start your reference document with a small table of contents that first lists the classes, defined types, and resource types of your module. If your module contains both public and private classes or defined types, list the public and the private separately. Include a brief description of what these items do in your module.
## Reference

### Classes

#### Public classes

*[`pet::cat`](#petcat): Installs and configures a cat in your environment.

#### Private classes

*[`pet::cat::install`]: Handles the cat packages.
*[`pet::cat::configure`]: Handles the configuration file.
After this table of contents, list the parameters, providers, or features for each element (class, defined type, function, and so on) of your module. Be sure to include valid or acceptable values and any defaults that apply. Each element in this list must include:

  • The data type, if applicable.

  • A description of what the element does.

  • Valid values, if the data type doesn't make it obvious.

  • Default value, if any.

### `pet::cat`

#### Parameters

##### `purr`

Data type: Boolean.

Enables purring in your cat.

Default: `true`.

##### `meow`

Enables vocalization in your cat. Valid options: 'string'.

Default: 'medium-loud'.

#### `laser`

Specifies the type, duration, and timing of your cat's laser show.

Default: `undef`.

Valid options: A hash with the following keys:

* `pattern` - accepts 'random', 'line', or a string mapped to a custom laser_program, defaults to 'random'.
* `duration` - accepts an integer in seconds, defaults to '5'.
* `frequency` - accepts an integer, defaults to 1.
* `start_time` - accepts an integer specifying the 24-hr formatted start time for the program.