Getting by with a little help from your friends in QA
September 16th, 2008 4 Comments
Graham Campbell writes:
We had some listener feedback about the Podcast on being the sole TA in an organisation (Being the only tech writer - Podcast #13).
Paul Welsh, a Technical Writer from Nebraska, USA, raised the following point:
"One thing that I don't think you mentioned is that there's no one to talk to when it comes to
your job. Not a big deal, but I've noticed it a few times lately as I evaluate tools and there's no one else here who would really get it, or be interested in the discussion."
It's a good point, and one that I feel is actually a big deal despite what Paul suggests. Beyond the evaluation of tools and procedures - something that demands a peer for meaningful discourse - the actual discussion of work to be done and requisite peer review are just not there.
For someone as new to the vocation as me - I mentioned in the Podcast I've been a Tech Writer for 2 years now - the absence of peer review is a knock to both confidence and, inevitably, quality. The fear of not producing a meaningful piece of work is bad enough without the added burden of knowing that, without peer review, mistakes and bad habits aren't being identified and dealt with.
I've offered before that Tech Writers can feel like we're considered last and least in the list of priorities in an organisation, and this feeling is only emphasised when you're flying solo.
However, Geoff Hart's article on Why do I need a technical writer? makes a good job of listing the very specific reasons a skilled Tech Writer is an important addition to any organisation.
In particular, his first point in reducing support costs:
"Technical writers think of the task from the user's perspective, not the designer's perspective. Thus, they explain better how users can reach their goals."
Which brings me nicely to the solution I found for my dilemma - conscript one of the Testers as a pseudo-reviewer.
Any software house worth its salt will have an internal team of quality assurance testers. Testers, like Tech Writers, have an inherent eye for detail perfect for finding any error in that tricky procedure you wrote or with the delivery method you chose (broken links in a series of Online Help Web pages for example). More importantly, testers are also looking at the tasks in the software from a user's (and a usability) point of view which, as Geoff states in his article, is a vital Tech Writer trait.
While Testers and Tech Writers have different sets of skills, they nonetheless both share the same attention to detail required to perform their designated function as well as an interest in the tools and procedures needed to "get it right".
I'd never advocate this as a permanent solution of course, but if you find yourself missing a spare Tech Writer or two and are on good terms with your QA staff, relying on their keen eye is a good stop-gap.
Potentially similar posts
- ITauthor podcast #36 – Acrobat and shared review of Web pages – October 2010
- Tech writer: a rose by any other name … – June 2010
- ITauthor podcast #34 – Testing testing 123 – May 2010
- Tech writing blogs – March 2009
- Articles – November 2008
September 16th, 2008 at 6:43 pm (#)
I once gave a tester a section of my online help to review, but the tester clearly lacked evaluative/analytical skills. He pointed out misspellings, incorrect button labels, or steps that were inaccurate -- this I welcomed. But he had no ability to comment on whether the topics were clear, concise, or worthwhile. He lacked a higher level analysis, which is what I was hoping for. He was so mechanical about it all. Other writers can evaluate overall organization, clarity of communication, style, continuity, etc.
September 17th, 2008 at 7:06 pm (#)
I'm in a similar position: tech writer of two years in a small company. Our tester is also good at finding my mistakes :)
The lack of formal review processes in a smaller company is freeing in a way. As you say, though, it can mean having little feedback about whether your documentation really works for the user.
September 17th, 2008 at 10:26 pm (#)
Having a formal review process is definitely a good thing, whether or not you have fellow tech writers to do the review.
Tom's right, it's important to get review comments on the structure, style, consistency and readability of what you've written.
But, unfortunately, sometimes you're just thankful to get any review comments at all.
September 18th, 2008 at 1:35 pm (#)
As a tester with ten years experience and who has reviewed many documents in his time, it is a not-insignificant mental gear change going from testing software to "testing" documentation.
As Tom mentions above, it is easy for Testers to be very mechanical and review documents at the same level at which most testing occurs; spotting visual issues such as spelling, formatting and, if you're lucky, grammar.
What Tech Writers need from their reviewers, and unfortunately what Testers spend too little time doing, is stepping back from the mechanics of what they are reviewing and thinking about things from a user perspective.
Therefore, while QA and Tech Authors have similar roles, similar outputs and can support each other, QA will never be a substitute for another professional Tech Author.
Also, Testers are usually amongst the most time-pressured people on a project, due to their unfortunate position at the tail end of most projects. This means that requests for reviews from Tech Authors are likely to receive a cool response, if one is forthcoming at all!