Adam, Thanks again for your reply. Here are some further thoughts.
To recap: Warnings such as this appear in the new CS API documentation: > "Warning: You need your own API key in order to use the Custom Search > element." ... "Without a unique key, these [code] examples won't work." But as you wrote above: > "... keys ... are not required for the Custom Search element ...." You further explained: > "... As part of the documentation rewrite, we took a firmer stance ...." > "... By using strong wording to increase key usage among new developers, the > intent is to help make sure they don't run into problems later. ..." IMO, documentation should be clear and true. While there may be good reason for 'strong wording' to a point, that warning is currently worded such that it may appear at worst untrue (as your comments appear to contradict it) or at best potentially confusing. As you say the aim is to "strongly encourage" key usage. I understand that there are good reasons for that. But the warning as it now stands could confuse not only newcomers, but also existing users of Custom Search and Site Search (who vary widely in skill levels and first-hand familiarity with the API). Presumably some who read the warnings might wonder if there's a need to update their existing Search Element code to use a key, though in fact that really isn't necessary for existing implementations (as you have confirmed). I might suggest replacing the warnings with something like this (I am borrowing some text from existing documentation and from your reply): "... IMPORTANT: All developers creating new implementations using this API are strongly advised to obtain and use an API key. Your API key helps us to contact you if we detect problems with your application. Developers using keys are also less likely to be incorrectly identified as misusing the API. Your API key can help us to help you avoid problems down the road. ..." Thanks for taking the time to read this feedback. -- omr -- You received this message because you are subscribed to the Google Groups "Google AJAX APIs" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/google-ajax-search-api?hl=en.
