# 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