Hacker News Reader

Comment by sph | Hacker News Reader

> The documentation reads like a tutorial, which is fine the first time you read it, and really annoying the next 99 times when you're just trying to find something.

Ah yes, the Ansible approach. I've used it for a decade, and I routinely get lost in its utterly terrible by-example documentation.

They are the golden standard on how not to write documentation.

God, I hate the Ansible docs so much, they are the reason I burned 30% of my Kagi search quota this month.

View on HN

I think more documentation teams need to know of the concept of Diataxis [1] so they can invest in the 4 different kinds of documentation developers turn to for help when picking up a new technology:

- tutorials;

- how-to guides;

- technical reference and;

- explanation.

1: https://diataxis.fr

This looks very nice and is something I have been searching for but didn't know existed. Thank you!

See also the C4 model "for visualising software architecture". https://c4model.com/

Thanks for this. This is something I kind of knew but would have been hard pressed to articulate, especially on the spot. Seeing it laid out like this is very useful.

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.

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.

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)

For stuff like Ansible (and other lacking software) docs i find that ChatGPT can provide the missing pieces.

Reply on news.ycombinator.com