Creating Good Content Requires Cross-Department Collaboration

by Tom Johnson on Sep 6, 2013
categories: findability

One traditional stereotype about technical writers is that they work long hours in isolation, almost like a hermit in a lone cell immersed in deeply technical material, trying to make sense of it all by themselves.

We know that stereotype is a recipe for failure. Collaborating and sharing information across departments is essential for creating the right content. But exactly how we are to collaborate across departments isn't as well defined.

In this post, I'll identify 5 ways that you can leverage knowledge from other departments to help you write better content. Especially in an agile environment, the faster you can compile the right knowledge, the better job you'll do as a technical writer.

Note that all of these techniques are critical for creating quality content. When you neglect any of them, content quality either suffers or you create more work for yourself. Also, this post will focus on departments in a software development shop.

Interacting with Quality Assurance

Quality assurance engineers (the people who test the code engineers build) can be a goldmine of information for writing documentation. QA engineers usually have a list of test cases to run against the latest build to make sure the features work correctly. You can pull from these test cases to get a better sense of how features are supposed to work, as well as any constraints or limitations with the features.

For example, suppose your ACME Software 2.3 version is set for release in two weeks (the pace of agile). You may have a notion of the features to be included, but QA knows precisely how these features are supposed to work. They may have already developed specific API calls to run against the features, or enumerated the possible values users might enter for fields, and so on. QA probably has an extensive list of tasks (called "test cases") to try out to make sure everything works.

These test cases can help prime your awareness of how the features work and give you a jump start in writing documentation for the features.

Interacting with Support

Your Support group (the ones who interact with customers to troubleshoot problems) almost always have a ticketing system where they track incidents/calls. By mining the support database for the most recent incidents, you can inform yourself about various issues users are dealing with. This information gives you a clear direction about important documentation features to focus on. It also lets you know problem areas that may require more documentation.

In an environment where you might work on dozens of different topics that all seem to command your attention equally, the information you get from Support can help you focus on the topics that really matter. You can use these incidents as a starting point as you triage your work; they can open up your perspective and give you a better sense of what your users are doing or trying to do with your product.

Interacting with Engineering

In almost every place I've worked, engineers (the people who build the software) frequently use JIRA, a bug tracking system, to coordinate and manage their work. When you tap into JIRA (or some other bug tracking tool), you plug into an awareness about what features engineers are working on, what features are planned for upcoming releases, what features are being fixed, what problems have been identified as bugs, and so on.

If you become intimately familiar with JIRA, you can stay ahead of the documentation game. You won't be surprised with sudden updates to the software that no one informed you about. You won't be left "out of the loop" — and feeling resentful for the neglect.

You'll also know just who to ask when you have a question. By looking at which engineers are assigned to which JIRA items, you have a contact point for questions. You can follow a JIRA item so you know when work begins and ends on an item. And you can pull together all items tagged with a release version to get a definitive list of what's included in the next release.

You don't have to attend every single scrum meeting and so forth to keep tabs on what engineers are up to. Just immerse yourself in engineering JIRAs. When you have a question, go directly to the right engineer for answers.

Interacting with Product Management

Product managers define the specifications about how certain features are designed to work. They build the blueprints that list out the use cases and the requirements for the engineers to build. Access to these specifications can help you understand the purpose of the feature so you can infuse your documentation not only with the "how to", but the why and for whom.

As you're gathering information about features, read through the original roadmap that chartered why the feature was built, the problems it hopes to solve, and myriad other details outside of the technical how-to.

Close relationships with product managers are also essential because product managers are usually the guides for the engineers. In some sense, the product managers are like waitresses in a restaurant: they gather information from the customer and then hand it to the cook/engineer to make. If you want to influence how the software is built (e.g., including a help button), route your requests through product managers.

Interacting with Implementation

This last group is a little more nebulous and varies from company to company. Implementation people are the ones responsible for customer success. They work with the customer to implement the product in an effective way. Like support, implementation people work in the "post-release environment," so no doubt the information you gather from implementation will be helpful for revision and supplementation to your existing documentation. But in an environment where content is continually evolving, the line between draft and published is blurred.

What information can you glean from your Implementation group? Implementation can give you a better idea about how your product is used. Not all customers use your product in exactly the same way. While Support may receive calls that provide similar post-release knowledge, incident logs are more scattered and random. The Implementation group can give you a picture from beginning to end about the customer's perspective. They can paint a picture of the customer life cycle, explaining how customers incorporated the product, the techniques used or not used, the considerations they faced, the challenges, solutions, and so forth.

Conclusion

Content quality doesn't usually appear magically on the page when you figure out how to puzzle pieces fit together. There is a tremendous amount of information to be gathered and learned from other departments. The more you can pull information from these groups, the better content you'll be able to create.

As you interact with these other departments, look for the following resources:

• QA test cases
• Support incidents
• JIRA items
• Product specifications
• Customer success stories