I tried out both Puppet and Chef a while ago, and was also a bit confused by the Chef documentation when trying to do anything beyond the basics.
While not brilliant, the Puppet docs seemed better and when added to the Pro Puppet book ( http://www.amazon.com/Pro-Puppet-James-Turnbull/dp/143023057... ) are more than adequate, so I just picked Puppet on that basis alone, and have not had any issues.
Another useful tool , in conjunction with Puppet/Chef is Blueprint which lets you build configurations from existing servers , http://devstructure.com/ .
Have you used Blueprint? I am really interested in it. Honestly, it seems like a bit of magic to me and wonder how well it works and what its limitations are.
While not brilliant, the Puppet docs seemed better and when added to the Pro Puppet book ( http://www.amazon.com/Pro-Puppet-James-Turnbull/dp/143023057... ) are more than adequate, so I just picked Puppet on that basis alone, and have not had any issues.
Another useful tool , in conjunction with Puppet/Chef is Blueprint which lets you build configurations from existing servers , http://devstructure.com/ .