Thanks for the feedback, and it is something we will be focusing on as we get closer to 3.0. We've made a big effort to make the generics as complete as possible so that they suggest and handle as many API issues right away, but we do need more example of how to plug the pieces together, and documentation on how they can be manipulated.
I hope you'll keep an eye on new examples as they arrive - given that this case was documented (just not where you thought), would you say that better example search would be helpful?
I don't know if better search in the examples would be that useful for me at least. For instance, in this case I didn't know I needed a UrlEncodingWriter until I found a forum thread that discussed what it is and what it does. Without that context, it's just another piece of magic code that I don't understand. That's the biggest problem with the examples right now - they're complex, complete, and super-dense. It takes me forever to tease them apart and figure out what each piece does (and how to modify them for our specific needs).
I can think of 3 things that would be extremely helpful:
1. Flesh out the API docs with discussion of what each class does, when it's appropriate, and common use cases.
2. Provide links from the API doc pages to examples that show usage of that class.
3. Create some "ground-up" tutorial examples that walk through building an example, discussing what each piece does and how it ties to the other pieces. Darrell's blog entries were a good start on this from a conceptual standpoint, but I'd love to see them continue to show actual use cases. Annotating the examples, in a way.
Based on Darrell's blogs and all of the really helpful forum posts from you and others, you guys have great technical writers. I'm really looking forward to the docs I know you'll crank out when the bug crunch finishes.