Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

Catalyst 6: QA Testing (Overlooked)

Apr 22, 2010 • beginners

As if I hadn't already been wearing enough hats, participating in both design, support, training, and help, I soon started to wear another hat: quality assurance (QA). We use JIRA as our bug tracking tool. It's mostly used by QA and developers to log bugs, enhancements, and user stories. I always knew it would be good practice to keep abreast of the items added to JIRA, so I could know if the application was in sync with the help, or if bugs were leaving gaps in the accuracy of my instructions. But that was the extent of how I perceived JIRA to be relevant to me.

As I was testing my instructions (one of the most important ways to review documentation), I kept running into bugs in the application. At first I forwarded them to the QA developers through email. I wasn't sure if they were already logged in JIRA or not, and I felt it wasn't my role to log bugs anyway.

But soon QA started asking me to simply log the bugs. They gave me the appropriate rights in the JIRA. Okay, I thought. I'll do it as a convenience to them. So I started to figure out JIRA, and I kept more up to date with the information and comments there. I started to log a few bugs, and then a few more. In a somewhat sadistic way, logging bugs felt therapeutic. Pretty soon I felt no fear at all and logged 25 bugs in one day. This got the attention of the developers and the project team in an astounding way.

Everyone was surprised at the degree of bugs I was finding. The QA lead had developed an extensive number of automated scripts, but he wasn't finding all the bugs I was finding. I was finding a surprising amount of bugs precisely because I was simply going through topic by topic in my help documentation and testing everything (really testing my instructions but also the application at the same time).

I realized that I had literally written a book on the application -- something no one else on the project had done. I knew the application as intimately and thoroughly as anyone else on the team, if not more. With this knowledge, especially combined with the user knowledge, I could see bugs in places QA never thought to look. Over the course of a week of heavy review of my help, I logged about 65 bugs.

One thing I was also doing was using SnagIt and Jing to show the bugs. All the other QA members just described the bugs with text. It quickly became clear that pictures were the preferred mode for developers to see bugs. They soon joked that unless the JIRA item included a screenshot, they wouldn't review it. After a few weeks, the QA team also started to include screenshots.

QA considered me an addition to their team and said I would make a great QA tester. I thought they might be upset at the QA spotlight I was taking, because I was logging three times as many bugs as they were, but instead they thanked me for logging the bugs and genuinely appreciated it. (It would save them face later to not have bugs found in the production release.)

Pretty soon in meetings I was no longer someone they passed over quickly at the end. I was a key voice in bug triage, scrum, and other meetings, where developers and project managers would need to evaluate the bugs they were going to fix. I wasn't just sitting there listening to others talk. Instead I was explaining the bugs I found, and evaluating the seriousness of the problems.

I noticed another thing -- if I logged a bug in JIRA, someone usually fixed it. Not always, but it was the secret passage way into influencing the application. Even small fixes involving textual changes were something I could sneak in and get done. Soon one of the new developers on the team starting coming to me to ask if his planned fix was all right with me. I already owned all the text in the interface, but now that domain was blending into functionality.

On one occasion, I found a screen to be particularly problematic. I had a tough time describing how it worked, and the video I created was even more problematic. I also logged about five bugs against that screen alone. I made such a big deal of it that I convinced the project manager that, despite the time crunch and our lack of resources to fix it, we couldn't skimp on this. He told me to get with the developers to redesign the page.

It wasn't easy. I sat there thinking for a while, somewhat stumped on how to fix and clarify the process. I brainstormed together with a QA person and developer, and within 15 minutes we came up with a solution. We, not I. Not a single person, but we.

This was another experience where I wasn't just documenting what is, or what had been coded. I was actually driving the design. I was determining what developers would work on through the JIRA items I submitted. I had zeroed in on the most problematic screen in the application and redesigned it.

We often come across problematic screens, but it isn't until you start logging bugs that it actually forces project managers and developers to formally evaluate the problems and make a decision. Logging bugs makes you extremely visible on the team, because it forces an intersection point between the developers, project manager, QA testers, and you.

At this point I realized that I was much more than a simple technical writer on the team. I was actually part of a team. I was an integral player, contributing everything from help materials to customer support and training to user interface design and quality assurance and the product roadmap.

My main role was still to deliver help materials. Of course that's one of my main contributions on the team, but it certainly wasn't the only thing I did anymore. I had moved from overlooked to one of the main actors on the project stage.

When I would travel with the product manager to introduce the application to new groups of people, he had a hard time describing my role. He didn't just say, this is Tom, he's a technical writer on the team. At times he would say, Tom is our director of user education. Other times he would say Tom is our usability specialist. Other times he would say that Tom is one of our team members. Other times he would just look at me and pause before trying to figure out how to describe my role. The role he pinned on me corresponded with the purpose of the meeting.

The need to expand our roles, to move beyond what our company pigeonholes us into doing, is one of the encouragements I received from Mark Hanigan, former STC president. In one podcast, Mark told me,

It's up to the technical communicator to market him or herself to the other individuals, the project managers, the appropriate departments within the company, saying hey, wait a minute, why do we have this separate entity of business analyst and technical communicator. I can help you with both. And we can provide deliverables that are faster, better, cheaper. And here's why. And then you go on to explain to them what you can bring to the table.

It is up to us. We can create the opportunities that transform our role, but it has to be a conscious action. No one will magically change our jobs for us.


Get new posts delivered straight to your inbox.

Subscriber count: 3,220

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.