By Enid Newberg, Fran Sardone, Lara Kulpa, Peter Johnson, and Yoel Strimling | STC Senior Member
Guest Editor’s Note: The following is a reworking of a number of email conversations that the authors had over the course of several months. I have rewritten these email exchanges (with the approval of the authors) into a “virtual conversation” to give them the feel of a coherent discussion. Thanks to Daniel Foster of TechSmith for introducing the authors to each other and to me.
Yoel: Technical communicators want to produce high-quality content that helps their readers do their jobs better, but they can’t really do that if they don’t know what their content consumers actually want. Most of the time, for various reasons, technical communicators only talk among themselves and don’t hear their readers’ voices.
So I had a brainwave. Wouldn’t it be great if we could get some actual content consumers to write an article for Intercom? Rather than just have a discussion about what readers want among a group of technical communicators, how about we open the conversation up a bit, and include the readers themselves?
So I’ve invited the four of you, Enid, Fran, Lara, and Peter, to put on your “content consumer hats” and talk about how you define the idea of “content quality.” Each of you will undoubtedly bring your own personal thoughts on what this means—and that is excellent, because quality is not “one size fits all.”
I think this will be a good way to both showcase the diversity of what content consumers think about quality, as well as to focus it into something that technical communicators can use.
Peter: I would say that content quality is like a conversation. That is, it’s an agreement between at least two people: the content creator and the content consumer or end-user. For this agreement to work, content creators need to know that content consumers approach their content with both implicit and explicit standards for what they want.
When I use content, I want it to both meet my expectations (I have different expectations from social media, a video, a newspaper article, a user guide, or a training session), as well as meet my requirements (no matter the type of content, I want it to be easy to understand, visually effective, and relevant to me).
Fran: For me, content quality means that every activity in the training session I’m in, or topic in the documentation I’m reading, must be appropriately contextualized to result in meaningful learner/reader engagement, typically organized around a clearly stated goal. If the activity is part of a course or document that incorporates several activities, then the goal must also link to appropriate and clearly stated outcomes in support of the subsequent activities.
As a content consumer, I sometimes find that there’s a gap in the logical flow of content leading up to/following up from an activity. Somewhere you’ve made an assumption that I will understand how and why this activity is meaningful. Even when an activity is introduced effectively, there is sometimes no meaningful integration with subsequent activities.
I typically see this as a symptom of either the content creator having only a superficial understanding of the content, or that they aren’t really subject matter experts (SMEs). Or maybe they are SMEs, but they’re so immersed in the content that they can’t step out from it. The passion for the topic overshadows compassion for the learner or reader.
Lara: I feel like both of you have definitely touched on some of the biggest pain points.
In my mind, “writing for users means thinking like users.” In other words, content has to flow tightly and logically from one idea to another based on how users use it.
As a content consumer, the one thing that frustrates me most is a lack of flow. In any kind of technical documentation, online or off, I want to follow up on anything I read with whatever question pops into my head at the time.
Some of the worst perpetrators of bad content flow are the biggest companies. I wish they’d talk with their customer service people. I wish they’d collate their live chat records and analyze them. I wish they’d give me what I’m looking for without me needing to click more than once or twice to get there.
I need to see that the content creator can anticipate my questions and provide me a direction to seek answers. Content flow needs to make sense and be intuitive.
Enid: Lara, you made a good point about the apparent disconnect between those who design a system, those who do the technical writing, and those who need help and use the content. Those who create technical documentation need to make sure that they get access to the customer service reports and buy-in for continued updating and improvement of the content.
Content quality is based on what content consumers think about the content, and getting access to customer feedback is a great way of anticipating what they want and how they are looking for it.
Yoel: Can you give some examples of either positive or negative experiences that you yourselves have had with content quality?
Enid: A couple of years back, I spent two to three hours with our local telecom company, because their online help had articles that no longer matched anything in their current offerings.
Between phone calls with technical support people who could help with the single instance but didn’t know why it wasn’t working as described, and sending long written commentary about the remarkable number of bad links, bad information, and circular references, I was finally able to get a very simple answer about how to consistently change the forwarding number for the office when not in the office.
Peter: I just finished an outstanding online course. I think that the attributes that made the course so good apply to all types of technical communication.
First of all, complicated activities and topics were presented in a way that made them easy to understand. For example, each time a new term was presented, a clear definition was given and repeated later.
The materials were broken up into short sections that were easy to process, and each section used practical examples with which I could identify. Several of the key concepts presented were things that were relevant to me and I could apply to my work right away.
Not only that, but each section was presented in a consistent manner, with a specific pattern. First the explanatory video with examples, followed by a summary of two to three key ideas presented in the video, and finally the challenges. Each section averaged about 30-45 minutes, which was just the right amount of time.
Fran: I had the opposite experience.
There were too many caveats and warnings about what not to do before I engaged with the activity itself (was the content creator afraid that I’d get the activity wrong?). How many tip boxes or callouts are required for me to review? Did they run out of time in creating this content? I got the impression that their successful teaching/instruction was prioritized over my learning.
Lara: A very well-known domain registrar and hosting company offers an extensive documentation and FAQ area on their website. Domain registration and Web hosting, however, while technically related, don’t usually have the same types of issues. When I went to this company’s help section and typed in “managing DNS records,” the first page of results showed me 3,901 results! (No, I’m not exaggerating, that’s what it said at the top of the page—is this Google? Nope. It’s the company’s site.)
After the first three entries (“Manage DNS zone files,” “Manage DNS in cPanel hosting,” and “Manage DNS templates”), which were still not quite what I was looking for, I kept scrolling.
“Manage DNS for your hosting account” (okay, that might be it).
“Manage Secondary DNS” (wait, maybe that’s it?).
“Manage DNS zone files for your domain registered at another company” (oh no … that’s what I wanted! I think?).
It doesn’t make sense. It’s not intuitive. And it frustrates the heck out of me.
And then, let’s say I actually find the page with the help that I need from within the current setup that they have. The “related articles” section has five items that could actually be related, and three that aren’t at all. Like, at all.
There’s also a “You may also like…” section, with additional “helpful” articles. It’s all over the place.
There’s literally nothing helpful here that doesn’t confuse people in the process.
Yoel: What advice would you give technical communicators about how to provide you with high-quality content? What do you want them to know?
Lara: I would suggest that the best thing to do is use an online documentation platform to maintain a tagging and/or keyword system, and offer bookmarked links to related or possibly related next steps.
You’ve got to have an intuitive and cohesive system that can work with the customer to anticipate what they need. And maybe, just maybe, if someone clicks too many things that don’t make sense, put them into a live chat, or tell them to write out their question and someone will get back to them ASAP—and then get them real help that way.
Enid: I would say that it’s very important to make sure that your content is reviewed by someone else, preferably a reader, but if that’s not possible, by an editor or another technical communicator who can act as a sort of “reader advocate.”
I have always believed that it takes a minimum of two people to get one brain, particularly in the technical world. Content creators can outline what they want to see from quality content, but without having a fresh eye to review the documentation, it will always fall short. When you prepare technical documentation, you already know the product, so you become blind to portions of the beginner’s mind and make assumptions that might not be valid.
Peter: When you start creating content, be it documentation or a training program, remember the following:
- Start with clear objectives—who are you writing for and what are you writing about.
- Use outlines and drafts to keep the entire project in perspective.
- Collaborate and communicate with team members, as well as potential clients or end-users.
- Use models of excellence whenever possible, including examples of quality work from respected developers, as well as developing templates that can prevent you from rebuilding everything from scratch.
Like I said at the beginning, quality is a conversation, and like any good conversation, there has to be clear communication both ways. For training sessions, this could be done using student assessments. How well did a group of students learn the material or skill presented? For documentation, this could be done using client surveys. For example, at the bottom of a customer support page, you could ask readers if they found the content helpful.
Fran: Begin with the end in mind. Ask yourself:
- What are the goals or outcomes that your project is working toward? Spell them out so that there is accountability for assessment.
- Stay on point and recognize when digressions and additional and supplementary information require separate treatment.
I would also say that content creators need to test the quality of their content with an objective reader/user, and pay attention to their suggestions. When it doesn’t make sense to your user, it doesn’t make sense—full stop.
Also, when activities are integrated into the content design, provide an introduction describing how the activity or interactivity will be experienced by the content consumer. Please don’t surprise us.
ENID NEWBERG (email@example.com) is the IT/Website Director at Kepler College. She specializes in leadership, online course site development for education, whole systems design, budgeting, strategic planning, synthesizing complex information, marketing, non-profit requirements, and organization.
FRAN SARDONE (firstname.lastname@example.org) is an adult education professional with a desire to connect people to learning opportunities via instructional design, multimedia, social media, storytelling, networking, and research skills to achieve their professional goals. Her experience spans academic, corporate, and virtual communities. She has a proven track record of working with subject matter experts (SMEs), respectfully and accurately conveying complex information and theories to promote learning and audience engagement.
LARA KULPA (email@example.com) is a mom, wife, and artist and has been working online in some form or another for over 23 years. She currently works as a marketing consultant to help businesses fix what’s wrong with their marketing plan and is the owner of Art by Lara, LLC.
PETER JOHNSON (firstname.lastname@example.org) is the Founder of Web Explorations (https://WebExplorations.com), a company specializing in course development and instructional design. He has over twenty years of experience creating and teaching college courses in computer programming and Web design. He has a Master’s Degree in Information Technology with a focus on Web programming and a Bachelor’s Degree in Organizational Management.
YOEL STRIMLING (email@example.com) has been an editor for 20 years and currently works as the Senior Technical Editor/Documentation Quality SME for CEVA Inc. in Herzelia Pituach, Israel. Over the course of his career, he has successfully improved the content, writing style, and look and feel of his employers’ most important and most-used customer-facing documentation by researching and applying the principles of documentation quality and survey design. Yoel is a member of tekom Israel, a Senior Member of STC, and the editor of Corrigo, the official publication of the STC Technical Editing SIG.