Testers and user documentation

Reading Time: 2 minutes

On Software Testers Speak Up Meeting #1 I met a colleague tester that is responsible in his organization for writing user technical documentation. At that time, I was strongly against idea that testers should do that activity, because testers are responsible for testing the system. So my advice to the fellow tester was to convince his project manager that testers should stop writing project documentation.

But his response was that testers in his organization are the most qualified for writing user documentation, and user documentation is one of the most important artifacts of the agreement with the customer.

They had a situation when customer database administrator dropped production database, instead of applying a database patch (stupid mistake according to every database administrator that knows its craft). User documentation that explicitly stated how database patching should be done, played significant role when customer wanted to blame testers organization.

Because of that information I had been thinking for several weeks after testers speak up meeting. For testers organization, customer documentation is integral part of their product, not just the system itself!
So I decided to ask for help. Twitter was my tool of choice.

karlosmid Karlo Smid 

@michaelbolton I met a tester. He doesn’t do testing because he has to write customer documentation all the time. How should I advise him?

I know about Michael Bolton and his testing magic for a long time. I met him at the STP2010 in Las Vegas where I attended his Rapid Software Testing course. Great thing about him is that he is doing free consultancy. Here is his answer.

michaelbolton Michael Bolton 

@karlosmid When writing customer documentation, I did plenty of #testing. Often, I found way more bugs than “testers” did.

michaelbolton Michael Bolton 

@karlosmid So, for your friend: 1) NOTICE that you’re testing. 2) Report problems, give repro procedure, explain /why/ they’re problems.

And immediately all become clear. I had an emotion about testers writing user documentation. That emotion got me thinking about fellow tester problem. I asked for help, and advice was immediately clear: “As a tester, your are glue in your organization”. That means ask a lot questions about every line that you put in user documentation. When you write user documentation, interact with others, ask questions about documentation stuff that bothers you. Don’t be just a dummy that writes it down.

Today, there was also one important Michael tweet that connects with his advices about writing user documentation:

@michaelboltonMichael Bolton
Published: Shapes of Actions; why #testing is often described by oversimplified modelsbit.ly/usxYU4 #Agile #PMP #PMI #PMOT #PMBOK

Read his blog post to further enhance your user documentation writing and questioning skills.

Facebooktwittergoogle_plusredditpinterestlinkedinmailby feather

Karlo Smid

One Comment

  1. I've often written user guides and technical guides for products that I have tested and in one company, the project manager even commented that the user guide that I've written was the best document he has ever read!
    I agreed whole heartily with your tester colleague that we, the testers, are the ones who know the system the most and are ideally suited for the role, provided that of course, you enjoy writing.
    For me, the process of writing and explaining how the software works in a document verifies the knowledge I have of the system, and in doing so, I did find new bugs during documentation which I have missed during my official role as a tester.

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.