Exposing our soft underbellies

Exposing our soft underbellies

on Aug 18, 09 • by Helen Abbott • with 5 Comments

Tom Johnson’s recent blog article (a must-read, involving ice picks and eyeballs) reminded me of one reason we want to move Klocwork’s user communication content to a Wiki: we want to talk to our users. Crazy idea! Let the doc team talk directly to the users? What stupid things might those literary types say? I ...

Home » Documentation » Exposing our soft underbellies

Tom Johnson’s recent blog article (a must-read, involving ice picks and eyeballs) reminded me of one reason we want to move Klocwork’s user communication content to a Wiki: we want to talk to our users. Crazy idea! Let the doc team talk directly to the users? What stupid things might those literary types say?

I confess that it’s taken me a long time to get to this point. Johnson says tech writers are often subject to figurative lobotomies, like “don’t bother the subject matter experts; they’re busy”, “don’t use your own voice on video tutorials”, and “don’t talk to your users”.

So we’re crippled from the start, and some of us take years to discover that we produce the most helpful help when we become more of an investigative journalist, actively engaged with those who create and test the tools and those who use them. (It seems fitting at this point to mention that one of the writers on the team is a former newspaper girl who recently created a video tutorial for Klocwork Solo, using her own voice.)

I’m also inspired by Sarah Maddox, who regularly blogs and tweets on tech writing, especially on using Wikis for user documentation, chatting with customers about the tools she documents, blurring the line between documentation and product management.

So, we’re going to expose our soft underbellies. We want to hear from our users directly, rather than the usual generic rants transmitted through our product managers (a recent example: “Need better documentation”). When you rant to us, we’re going to want details. How exactly is the help not helpful? What page made you throw up your hands and curse us? And telling us what works can be just as effective as telling us what doesn’t.

Related Posts

5 Responses to Exposing our soft underbellies

  1. Sarah Maddox says:

    Awesome! I hope you get a lot of positive feedback from readers and tech writers. I really like Geoff’s comment above, and it’s also similar to a lot of the feedback we get on our own documentation.

    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

    • Helen Abbott says:

      Thanks Sarah! You’ve captured the issue well. I’d already seen your “tips of the trade”; it’s a great idea. I’ll keep an eye on it and think of how we can apply something similar here.

  2. Geoff Babb says:

    Helen,

    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

    • Helen Abbott says:

      Geoff, thanks for the feedback. You’ve echoed what we’ve been hearing lately, but I will definitely take you up on your offer of more detail. We want to bounce our plans off customers as we tackle revamping the help to include more “why”.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Scroll to top