[mschuster91]

What is wrong with the Ansible documentation?! Almost all Ansible module documentation pages follow the same structure: a one-sentence synopsis, a list of OS packages needed to be present on the machine where Ansible runs and on the target machine, a table of parameters including aliases, default values and other hints, a list of attributes exported, some notes, and real-world examples.

It doesn't get more clear than that.

[sph]

Outside of modules documentation, the rest of Ansible docs are examples. For instance, there is no page where all ways of accessing inventory variables are listed. Or supported jinja filters. They are all scattered in a myriad of examples, which you have to read, carefully, to find what you need.

https://docs.ansible.com/ansible/latest/playbook_guide/playb...

On this page there is no quick index of all the functions available, their argument and a short summary of how they work. You need to synthesize this information yourself by reading through ALL the examples, and hoping your niche use case is listed.

There are more than one type of documentation, with different use cases. There's the tutorial/list of examples, which Ansible excels at, and is ideal for a first timer reading the docs from cover to cover. Then there's the API reference with quick index, for intermediate to advanced users, where they know roughly what they need, they just need to find it. In this, Ansible's docs fail dramatically.

[mdaniel]

I am certainly not one to defend the new ansible docs, but part of the woes that you're describing are due to the fact they just doubled down on `ansible-galaxy install` based setups, meaning there isn't "an answer" to what filters are available in ansible

The authoritative answer to what filters are currently available in your distribution is by running `ansible-doc -t filter --list` which does include a summary line, although for some of them it's "geez, thanks" just like any open source collection of disparate modules glued together

I used to actually build the ansible docs locally with singlehtml because I despised that chopped-up view, but now that they're all "galaxy all the things" it's practically useless again (although I will also say that building it locally and eliding all their tracking bullshit makes the pages load like a bazillion times faster, so ... still valuable in that way)