I've started using it over the last month. The docs on the web site are good and this hands-on tutorial was also helpful:

https://github.com/leucos/ansible-tuto

I'm actually not sure it's better than the shell scripts it replaced so I may end up switching back.

I've to disagree about the state of the ansible documentation, I guess. As far as I understand the website was restructured not too long ago and a lot of stuff is .. broken. I fell back to using the Google Site Search thingy to find anything, because ansible's documentation lacks any kind of index/reference (except for the modules page, which is nice). There's a good deal of magic involved, and passages in the documentation even state stuff like 'there are a couple of these magic variables, but not too much' (Note: No list is provided).

In general I hate the state of the documentation. It's barely usable.

I do like the simplicity of the format (.yml) and the architecture (no agent required, only dependency is python and I think even that can be bootstrapped via python).

My playbook (see above) certainly feels like a shell script packaged in .yml format, but .. I stumbled over and over again when I tried using ansible's modules (examples: No way to create postgresql roles without a password, no way to load data into postgresql => Two things I've to do via shell: or command: in my project).

Bottom line: I'm happy with the state I have, but I'm far from happy with ansible as a technology and probably wouldn't use it as it is for the next deployment project.

The things I really like about ansible compared to shell scripts is:

- jinja2 templating for config files - roles & tags - many error-cases already thought of and coded around.