We often talk about how high-quality Ansible content enables us to enforce the desired state on target hosts. Module parameters play a crucial role here because we use them to describe the expected result. But what about Ansible roles that do not have parameters?
Ansible roles use variables to customize their behavior. And since variables serve as parameters in Ansible roles, we, Ansible content creators, should document them with the same care as we document module parameters. The rules we should follow when describing role variable are:
- Each variable must have a short description.
- Variables with default values must note what the default value is and why we chose it.
- If the valid variable values come from a predefined set, we must list that set's content.
Where should we put this information? Right now, the best places are the reference section of the documentation site or the top-level README file in the Ansible Collection. That last one is incredibly convenient since Ansible Galaxy displays the README file content.
Top comments (0)