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.

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.

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