[picheny]

We really appreciate the comments and will try to fix the problems. To be honest, sometimes developers can't see even the most obvious flaws in documentation. If you can highlight even one incomprehensible point it would help a lot to accelerate the revision process.

[sk5t]

Overall the BlueMix and Watson documentation is very green and fair to call alpha-stage. This problem tends to all directions, although if a specific example would be helpful, trying to discover what load balancing options exist within BlueMix was something I tried and failed to learn last week.

For a Watson-specific example, at least a few months ago it was the case that putting together a full-featured client implementation for Q&A required poking around several obscure webpages and then plenty of runtime experimentation on top.

[afarrell]

This talk at pyTexas is really good for laying out specific Questions to ask yourself that can guide you to better docs: http://www.pyvideo.org/video/3167/keynote-developer-experien...