Fixed bug in Partial Search example, Completed documentation on Partial ...

[rberger]

...Search

[sethvargo]

Hi @rberger. Thank you for the Pull Request. I am willing to fix the broken API call as you pointed out in the other PR, but I do not think it's wise to replicate the documentation from partial search in this README. If you look at the partial_search method in ChefAPI, you can see that it just returns the response from the Chef Server. If ever that changes, I would like Chef to handle the documentation, not me. There are plenty of examples in the Chef docs about partial search queries that I do not think we need to replicate them here.

[rberger]

From what I understand and what caused huge confusion for me (or maybe I'm still confused if I'm wrong here) the chefAPI expects the keys parameter to be a hash that has a top level key called :keys where as :

:keys => { 'name' => [ 'name' ],
             'ip'   => [ 'ipaddress' ],
             'kernel_version' => [ 'kernel', 'version' ]
           }

Whereas chef-api expects it to just be a hash of key/values with no top level :keys key

 { 'name' => [ 'name' ],
             'ip'   => [ 'ipaddress' ],
             'kernel_version' => [ 'kernel', 'version' ]
 }

Plus the whole idea of passing in attribute keys as an array of strings is hugely confusing and so fundamental.

I think that people who are fluent in these tools that do so much ruby magic don't grasp how hard it is to use them by others, even for people who are ruby fluent. Having to translate from one set of magic to another makes it worse.

Having simple examples is soooooo helpful.

Besides this search issue that I spent a 1/2 day figuring out (and thus wanting to document) I've had almost as much difficulty trying to figure out how to use chef-api just ot update a nested node attribute. You don't show that anywhere. And having the Node docs just point to the Base docs isn't so helpful. I did finally figure it out but I had to mess with things in the ruby repl for a while.

But I will send you and updated pull request with just the API changes as soon as I can. Hopefully I'll have time to turn the other stuff into a blog post.

[fusiondog]

I found the docs in this PR helpful. If you aren't going to include them, perhaps you could link to the other documentation.