Ah, review comments. We have such a love/hate relationship with review comments. Like a passive-aggressive relationship. A few weeks ago, I wrote a post on how to deal with an influx of review comments. Thanks to everyone who commented and added thoughts on various LinkedIn groups and here on my blog. I always appreciate hearing from you.
After writing that post, I started thinking about my review comment dream team. Our best review comments come from people who have a wide variety of skills, knowledge, and experience. That means, they do all different kinds of jobs. Here is my technical documentation review comment dream team:
- Engineering. I love comments from engineers. After all, they are the ones creating the product. What I love even more is when multiple engineers see each other’s comments on a draft. Often, engineers work on individual components of the product. They actually learn how other components work when they read tech doc review comments from their peers. Yes, this can wreak havoc on a draft, as they argue about how the product works/doesn’t work/should work/can’t work. But, man, it is nice to get all of those smart people responding to me and to each other. I’ve seen disasters averted by the sharing of product knowledge that is contained in a draft document.
- Test / Quality Assurance. These are the people who actually test the product. They are the ones who know how it really works or doesn’t work. When working with QA, I like to get a copy of the test plans. Comparing the features they will be testing to the examples and configurations that I am writing about can be very useful. It’s even better if the testers can validate the procedures I’ve written in my configuration examples.
- Technical Support. Tech support engineers have a vested interest in making sure our content is accurate. After all, they are on the receiving end of the questions and problems customers run into when we have errors. They also look at the content from a different point of view than engineering. They are interested in both accuracy and understandability. I’ve often seen contentious relationships between tech support and tech doc. I’m not sure why this is. They should be our biggest allies and they should see us as their first line of defense. We should view them as the people who have intimate knowledge of how the product is actually being used. No one else in the company can provide this valuable input on our content.
- Product Management. Product managers are the ones who oversee the product from conceptualization through distribution. I think of them as product parents. They have a vested interest in the overall success of the product. They also have a clear understanding of the market, the customer, and the sales process (at least they should…).
- Marketing. It’s always nice to have someone from the marketing group review your draft. While they have a slightly different vocabulary and style for their content, using similar positioning and messaging across the product content makes for a more unified story. I have encountered situations where marketing and tech doc had completely different use cases for the product in their content. Even if the product could be use in both situations, it can be confusing to customers. For example, if marketing is positioning a router for small business, but the examples used in the documentation focus on home installation, the result could be confusion and return of the product. It’s good to have everyone on the same page (pun intended).
- Training. Years ago, I was responsible for technical training for a networking company. One of the most satisfying and helpful relationships we had was with the technical documentation group. We had a workflow where the tech writer was responsible for creating the conceptual explanations of various features. The training group was responsible for creating procedures for lab exercises. We shared and reused each other’s content widely. Our labs became examples and procedures in the documentation. Their explanations became the concepts in our courseware. This was years before XML, structured authoring, and reuse. It was quite a manual process. But, even back then, we understood the time savings of not having multiple people writing the same thing. With today’s tools, this should be a no-brainer. However, there are many companies that deploy state-of-the-art tools, only to stay silo’d within their own departments.
- Legal. I’ll be honest. I never really liked sending my content to legal for approval. They always seemed to be nit-picking at the tiniest things. And demanding! Heaven forbid you don’t put in a change that legal has recommended. Well, they are the legal department and their job (among other things) is to keep the company from getting sued. Legal review is usually mandatory at companies. Talk about a love/hate relationship. But, they are a necessary part of any review dream team.
- Editing. I love editors. I really, really do. Editors take fabulous meandering thoughts and straighten them out. Editors keep track of all of the big and little details. Editors can view a suite of content from a high level and make sure that it holds together developmentally. Given time and resources, they can look at all product suites in the company and insert parallelism, flow, and other developmental items that really take content to an whole new level. On the other end of the spectrum, editors go deep into the minutia of commas, semi-colons, and sentence structure to ensure readability, consistency, and adherence to corporate terminology and style. I’m very lucky that I had a brutal editor early on in my writing career (yes, Amy, I am talking about you!). Even with my background and training, it was my editor who really taught me how to write. Never underestimate the value of a good editor.
- Translation and Localization. My review comment dream team includes at least one person from the translation team. This person looks at the content from the standpoint of translatability and cultural fit. Having someone from translation look over your content before it is finalized (and then given to translation!) can save the company a tremendous amount of time, money, and frustration at the very end of the process. We’ve all heard the stories about what happens when non-translatable content gets translated in different ways, and the results are misunderstandings that cause embarrassment or even law suits.
- Peers. Last, but certainly not least, are other writers and peers in the organization. Peer reviews have always been a valuable method of getting feedback on technical and stylistic issues. If you are writing the online help system for a product and someone else is writing the installation guide, sharing notes and reviewing each other’s work can save a lot of time and energy later in the process. Single-sourcing and reuse also plays a big role in the peer review process.
The review process can be one of the most frustrating aspects of being a content creator. Putting together a team of experts to review content is not easy. Getting buy-in from all of these groups can be challenging. Getting a commitment from individuals in each group can be difficult. And actually getting people to provide their comments can seem like an impossible task. Assuming you’ve made it past all of these hurdles, having your reviewers provide comments of value (the nirvana of the review process) can seem insurmountable. Nevertheless, the review process is one of the most important stages of creating good quality, usable information. Without reviewers, we might be writing fiction.
Val Swisher is the Founder and CEO of Content Rules, Inc. Val enjoys helping companies solve complex content problems. She is a well-known expert in content strategy, structured authoring, global content, content development, and terminology management. Val believes content should be easy to read, cost-effective to create and translate, and efficient to manage. Her customers include industry giants such as Google, Cisco, Visa, Facebook, Roche, and IBM. Her fourth book, “The Personalization Paradox: Why Companies Fail (and How to Succeed) at Creating Personalized Experiences at Scale,” was published in 2021 by XML Press.
Val is on the Advisory Board for the Technical Communications Program at the University of North Texas. When not working with customers or students, Val can be found sitting behind her sewing machine working on her latest quilt. She also makes a mean hummus.
Val is on the Advisory Board for the Technical Communications Program at the University of North Texas. When not working with customers or students, Val can be found sitting behind her sewing machine working on her latest quilt. She also makes a mean hummus.
Latest posts by Val Swisher (see all)
- How to Make Conferences More Inclusive for the Hard of Hearing Community - December 2, 2024
- Preparing Content for AI: 6 Reasons Why You’re Not Ready - August 29, 2024
- How to Be Inclusive in the Workplace: My Experience as a Hard of Hearing Person - August 12, 2024
