# Ansible Community Documentation Toolkit
###### tags: `Documentation`

This toolkit helps you add documentation to your Ansible project or improve your existing documentation.

## Creating new documentation projects

Ansible projects starting a new documentation effort should follow these guidelines:

* Markdown is simple, ubiquitous, and familiar with to most contributors. For these reasons the Ansible community team recommends markdown as the format for doc pages.
* [mkdocs](https://www.mkdocs.org/getting-started/) is the recommended tool for building the documentation from markdown.
* [ReadtheDocs](https://readthedocs.org/) is the recommended place to publish documentation for Ansible projects.
* The [Ansible style guide](https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html) is available to help ensure your project is well-written and follows technical documentation styles.

### Using MKDocs scaffolding

Add a `mkdocs.yml` to your project root directory and modify the `nav` section to match your proposed navigation/set of guides:

---
site_name: Ansible <project name> Documentation
site_url: https://<projectname>.readthedocs.io/
repo_url: https://github.com/ansible/<projectname>
edit_uri: blob/main/docs/
docs_dir: docs
strict: true
use_directory_urls: false

theme:
  name: "ansible"
  features:
    - content.code.copy
    - content.action.edit
    - navigation.expand
    - navigation.sections
    - navigation.instant
    - navigation.indexes
    - navigation.tracking
    - toc.integrate
  palette:
    - media: "(prefers-color-scheme: light)"
      primary: teal
      accent: blue
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: teal
      accent: blue
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  local: en

nav:
  - index.md
  - Installation:
      - installation/install.md
      - installation/upgrade.md
      - installation/uninstall.md
  - Getting started: gettingstarted.md
  - User Guide:
      - user-guide/<content1>.md
      - user-guide/<content2>.md
  - Contributors Guide:
      - contributors-guide/contributing.md
      - contributors-guide/release-process.md
      - contributors-guide/author.md
      - contributors-guide/code-of-conduct.md
      - contributors-guide/get-involved.md
  - References:
      - references/cli.md
      - references/porting_guide.md
      - references/roadmap.md
exclude_docs:
  README.md

plugins:
  - autorefs
  - markdown-exec
  - search

markdown_extensions:
  - admonition
  - def_list
  - footnotes
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.superfences
  - pymdownx.magiclink:
      repo_url_shortener: true
      repo_url_shorthand: true
      social_url_shorthand: true
      social_url_shortener: true
      user: facelessuser
      repo: pymdown-extensions
      normalize_issue_symbols: true
  - pymdownx.tabbed:
      alternate_style: true
  - toc:
      toc_depth: 2
      permalink: true
      

### Using Sphinx scaffolding

### Setting up ReadTheDocs for publising

We publish ecosystem documentation to The ReadTheDocs site. To setup your project for publishing:
1. Create ``readthedocs.yml`` in your project root directory:

# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# RTD API version
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

mkdocs:
  configuration: mkdocs.yml

python:
  install:
  - requirements: ./docs/requirements.txt

2. Coordinate with the Ansible community team to set up automated publishing.

### Adding your docs to the Ansible ecosystem
Reach out to the community docs group on Matrix or the forum to request that we add your docs to docs.ansible.com/ecosystem

## Fundamentals of creating documentation

[Diataxis](https://diataxis.fr/) includes a good set of guidelines on how to write different types of documentation. The next sections will summarize this for quick reference.

### Tutorials / Getting Started guides
We tend to call these Getting Started guides. They are a quick introduction to the new user (or developer) to help them get something done. The focus is on doing. The [Ansible Getting Started Guide](https://) is a good example of this. Tutorials should have steps (procedures). We'll cover procedures in the How-to guides section.

### Explanations/concepts
Explanations or concepts describe the 'what and the why'.

See Red Hat's [concept explanation](https://github.com/redhat-documentation/modular-docs/blob/main/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc) for further details, but keep in mind it uses asciidoc, not markdown.

### How-to guides/procedures

These are what your readers will mostly use.

They should also focus on what are called 'user stories'. User stories help you transform what is a development/product feature into something a user or developer wants to achieve.

`as a <type of user> I want <some goal> so that <some reason>`

You should write these procedures as a series of steps, with an introduction sentence.

To watch your favorite sports team:
1. Search for what TV or streaming service televises it.
2. Subscribe to that service.
3. Set a calendar reminder so you don't forget the game.

See Red Hat's [procedure explanation](https://github.com/redhat-documentation/modular-docs/blob/main/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc) for further details, but keep in mind it uses asciidoc, not markdown.

### Reference

References are the facts--lists, tables, and so on. Your readers refer to these to help them with items like what kind of parameters or options are available and so on. [Ansible modules](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/copy_module.html#ansible-collections-ansible-builtin-copy-module) are an example of reference material.

See Red Hat's [reference explanation](https://github.com/redhat-documentation/modular-docs/blob/main/modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc) for further details, but keep in mind it uses asciidoc, not markdown.

## Types of guides to include

**note** A guide may only be one page if that is all that's needed for your project.

Your project likely needs the following types of documentation:
* installation
* getting started
* configuration/CLI reference
* user guide
* contributor or developer guide

### Installation Guide
This is how to install your project. It should be procedure focused and include:
- Installing
- Uninstalling
- Upgrading

Your installation guide may need to refer to a configuration page in the References section for initial setup.

Consider including procedures for more than one OS/environment if your project supports this.

### Getting Started
This guide acts as a tutorial for the reader. It should cover a simple scenario that the reader can follow to get their first 'thing done'. This is the 'Hello World' for your project.

See the revamped [Ansible Getting Started](See https://docs.ansible.com/ansible/latest/getting_started/index.html) for a good example.

### References

**Configuration**
This should be in the reference section and covers any required configuration files. This is typically a reference format. See [Ansible configuration](https://docs.ansible.com/ansible/latest/reference_appendices/config.html) for an example.
Consider if your project can autogenerate the configuration from code as the best way to keep docs and code in sync.

**CLI Reference**
This should go into more detail than the man page provides.

**Porting guide/changelogs**
As needed for your project.

**Roadmap**
(ff your project provides a roadmap)

### User Guide
This is where you want to really think not just about what features your project provids, but what problems it solves. These are your 'How To' pages. Again, consider those user stories:

`as a <type of user> I want <some goal> so that <some reason>`

Think of all your features as like elements in a plane's cockpit. Your reference material will describe each button, switch, and display panel.

What your User guide does is tell the user how to fly the plane:
- Taking off
- Landing
- Engaging autopilot for a good cross-country nap

Something else a good User guide has? Validation or troubleshooting help. What to do if you are landing your plane and the landing gear won't engage??

So a generic user story/use case will have the following topics:
* What is this use case and why would the reader want to use it?
* Numbered procedure that takes the reader step by step to apply this use case.
* Troubleshooting/verifying the end result (if applicable)

NOTE - a user story/use case should not list every possible option a reader could use. That detail should be in a reference section, or in a follow-on procedure.

### Contributor guide
As these are open source projects, you want to give your potential contributors and easy entry into your project. Keep in mind contributors can go beyond code contributions.

Your contributor guide should include:
- reference to the [Ansible code of coduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).
- communication channels you use (matrix, future forum etc)
- how to set up their development environment
- Where your issues/PRs are tracked etc