The question is tricky — just how much specific use-case and scenario-based information can we put into the docs? On the one hand, it’s what readers find most useful when they can identify with the scenario we choose. On the other hand, we can’t include all scenarios. Also, maintenance can become a bit of a nightmare, if the product changes significantly with each new release.

One idea we’re trying out at the moment is to link from the docs to external blog posts, written by our customers and community developers, that describe specific use cases. We’ve just started doing this, by adding pages we call “Tips of the Trade”. Here’s an example.

Thank you for mentioning me and linking to my blog, and good luck with this experiment!
Sarah

A couple of issues come to mind…

- My overall characterization of KW documentation is the old cliche about trying to learn a language by reading a dictionary. The documentation is long on “what” but short on “why”. It’s a great reference manual if you already know what you want to do, not so much if you’re looking for creative ways to apply the technology.

- Related to the above is the need for deep detail use case documentation, particularly around customization of rules, mining of metrics, etc. Stringing together a full tutorial on setting up a metrics framework, or applying the data that is provided, or filtering unwanted defects, or adding and managing a set of custom checkers (along with why I’d want them in the first place) would be a welcome addition. I think there might be a corresponding impact on overall product quality as it would walk someone in the company through the process of using the tool “in the large”, rather than testing it “in the small”.

I’d be willing to develop and elaborate on these ideas if you want to contact me.

Geoff