Ansible is my choice too, but here's the things that trip me up or could be improved. Apologies in advance for not raising them in the proper manner. (mailing list, issue list)

The inventory docs is a single page. Specifying a directory or a host file as an inventory seem to work but it's quite unclear how the two differ in behaviour. One problem with specifying a directory is that everything in the directory is interpreted; I had a README.md in there which resulted in baffling errors.

Dynamic inventory is also way under documented; a brief intro then two giant examples (ec2 and cobbler). It needs a tiny 'hello world'-ish example. My first attempt produced output in 'ini' format'. It was almost by accident that I tried json and happened across something that worked.

But error reporting is the worst. So often ansible will produce error messages like 'please specify an inventory' when you did specify an inventory. The problem is that you misspelled the inventory file or it couldn't be read. No mention of the file's name or whether even any attempt to read it is made.

(tangentially - This latter problem seems to be endemic to Python and Java and perhaps most languages that have exceptions)