Blending Tech Comm with Support

by Tom Johnson on Aug 26, 2012
categories: findability

Defining my role is not an easy task, and I see it continue to evolve as I get more experience as a technical writer. Recently I have added user support and user advocate to the list of roles I play.

Although I often don't have time to play a support role, I've found that when I do engage in support activities, it provides me with a wealth of useful information. I recently added a "Submit Feedback" link in my documentation. Through this link, I receive about 5+ emails a day related to various applications.

The Submit Feedback link is a Javascript email call that I embed in my online help master page. When a user clicks it, the link opens an email message and inserts the page the user was on in the documentation. This gives me context and lets me know a little about how people were using the help. Here's that little snippet of code in case you're looking for something similar:

Most of the feedback involves frustrations with the application. Many users note bugs or quirks in the applications that I was unaware of. For example, I didn't realize that a certain button didn't appear in Internet Explorer. I never use IE (except to briefly check things), and I somehow overlooked this issue in the JIRA backlogs of the project team. When a user asked about it, I investigated the matter and sure enough, no button. I updated the documentation with a note about the missing button in IE, and I ensured there was a JIRA item for the issue.

Other issues are more difficult. A user wrote to say a certain feature wasn't working as he expected, and he wasn't sure if it was a bug or a misunderstanding. I started to question what I wrote in my documentation, and during lunch with some engineers and QA team members, they said the issue had been something they recently discussed. We've gone back and forth on that issue multiple times, the QA guy explained. Then the developer noted that there was a bug in the application about this issue. This issue would have never surfaced without the feedback from the user.

Another user wrote to explain his frustrations with certain functionality in an application. It just doesn't seem to be working as described in the documentation. I thought, Oh really? Let me test that out again and see if anything has changed. What exactly is the user trying to do, and where are we going wrong? The feedback prompted me to reevaluate my documentation on that topic and examine where I might not be communicating concepts and workflows clearly.

Going through support issues with users provides me with phenomenal feedback about the documentation and application. It lets me know just where the documentation breaks down -- either because the processes aren't clear enough, or because of bugs or other issues in the application.

But just answering support for an application isn't enough. As a user advocate, I make sure constant feature requests appear in the JIRA backlogs of the appropriate projects. JIRA is our issue defect tracking system, similar to AgileZen, Bugzilla, iOS Ticket, TFS, or some other system.

I make sure bugs are logged in JIRA. I connect the project team with end users by analyzing this incoming support and feedback. I don't believe anyone else in an IT organization is better equipped to play this role than the technical writer. We are the bridge between end-users and project teams.

Other Candidates

Perhaps a support agent in a call center could do these same tasks. However, the support agent has several limitations. Most likely the support agent is one of many other agents. Their knowledge about products may be superficial; they escalate any real issues to the engineering team to investigate.

Support agents often don't log bugs in JIRA, or even know much about a team's JIRA site at all. This means issues the support agent responds to rarely make it back to the project team in a queue for the team to address. The bug never gets entered into the team's queue to fix. Unless a project manager actively monitors support tickets, this information goes unnoticed. Since project managers tend to be busy people, it's easy for the feedback to fall through the cracks.

Most importantly, though, the support agent usually isn't in a position to add to the documentation to prevent more calls from coming in. The support agent may have access to an internal knowledge base, but not to the external documentation the user accesses and reviews. Without an ability to contribute to this body of user-focused documentation, the support agent has no real ability to help inform other users about issues and other important information before they contact support.

In contrast, the technical writer can do all of this and more. The technical writer is dedicated to the project long term, so he or she acquires a subject matter expertise about the project. This allows the technical writer to resolve issues directly and escalate only those issue that are truly bugs requiring resolution.

The technical writer can log bugs directly in JIRA to connect the project team with this incoming feedback. The information doesn't simply fall into an internal metrics bucket somewhere. Bugs get logged, engineers get updated in scrum, and issues get discussed in project meetings. The technical writer becomes the user champion and helps align the team's focus with actual issues and concerns users are having. No longer do development teams make decisions based on their own internal boardroom decisions; they make decisions based on actual data coming in from end-users.

When the technical writer updates the documentation with additional notes, bug alerts, clarified steps, etc., the number of support calls goes down. The user experience improves. The technical writer creates a more informative product that solves real user problems.

Drawbacks

The only drawback in having technical writers play support roles for their applications is  bandwidth. Usually technical writers do not have time to busy themselves answering email, investigating alleged claims of bugs, logging in to user accounts to explore issues, or attempting to replicate issues. It requires a lot more time to play this role.

Further, this writer/support model contributes to an ongoing billing model for the tech writer. You're no longer just "done" with documentation once your product is released. You must continually monitor feedback, investigate issues, respond to users, log bugs and enhancements, and improve your documentation. The process is a continual effort, something that often doesn't have a clear beginning or end date, nor a clear budget allocation.

Additionally there's the question of value with roles. When I play a support role, how do I communicate that I'm adding more value than simply "technical writing"? I'm advocating for the user, helping align project teams with user needs, reducing support calls, and improving the user experience. But where are my deliverables?

Changing the Model a Bit

Although the "Submit Feedback" model provided me with excellent feedback, it had several problems:

• E-mails landing in my inbox were siloed from others on the team, especially the project leader.
• The 1:1 response didn't reach other end-users searching for the same questions.
• My engagement with support activities mostly went unnoticed because only I knew how many e-mails arrived in my inbox.
• I couldn't take advantage of volunteers helping out with responses.
• Feedback coming in from users was fragmented into several channels.

Because of this, I changed the Submit Feedback link to a user forum link. In the forums, experienced volunteers continually monitor and try to help users. I entitled forum moderators with the ability to escalate forum issues into a JIRA workflow, which I promised to carefully monitor.

It's too early to tell whether the new model solves some of the problems of the above bullets, but it certainly has potential to scale. Either way, the idea is the same: Engaging in support provides technical writers with incredibly useful information for technical documentation.