Let’s talk about docs

Let’s talk about docs

As documentation evolves beyond the written word, what will its future look like? Three expert tech writers and communicators share their takes on what was, what is, and what they think will be.
Part of
Issue 6 August 2018


Ben Woelk is vice president of the Society for Technical Communication. He’s worked in technical communication for more than 20 years and teaches university classes on computing security and technical writing and editing at the Rochester Institute of Technology in Rochester, NY.

Toni Ressaire is a technical communicator, trainer, and consultant. She’s worked with companies in the software development industry on five continents and is a founding member of the Information 4.0 Consortium.

Sara Feldman is content experience manager at MindTouch, a support service platform. She has over 10 years of experience as a technical writer, primarily in the software industry and focused on online support, and is currently the president of the San Diego Chapter of the Society for Technical Communication.

Content has been edited and condensed for clarity.

On the current state of technical documentation

Ben Woelk: Digital documentation now is where it’s been for the last two years. What used to be referred to as technical writing we’re [now] talking about as technical communication, because there’s a broader range of areas people are working on and a broad range of types of outputs. For many years, the idea of “technical writer” was somebody who would work on documentation for software or hardware.

Toni Ressaire: I remember when I was learning how to use Dreamweaver almost 20 years ago, I had a book that was about an inch and a half thick that I used to learn how to use this software. Of course, that’s what we had for any type of product. Eventually we moved away from printing to PDFs because people could just download them online. That made things a little easier.

And eventually we moved to help online. We even started using videos for teaching people how to do things. I think that 300-page documents will still be [around] somewhere in the background, but that’s not the primary way a user figures out how to use something [these days].

Woelk: As new technologies became available, the field in general moved on. You have a lot of people who understand that we need to embrace new technology [in order to produce] content in areas that people are interested in, where they need it, and in ways that they can access it.

Sara Feldman: Documentation becomes relevant far sooner in a customer’s journey than it used to. In fact, it becomes relevant at the very, very beginning of a customer’s journey, whether that’s automated or with a human. Customers have higher expectations, and for them, self-service is already more than just troubleshooting once they run into a problem. I think we as content professionals have a way to go. I think we’re behind the curve. I think consumers are beating us at this game, and that becomes really evident in how content is delivered.

Ressaire: Some of us are moving away from the term “documentation.” We’re using terms like “information” because the technology is changing so rapidly.

Woelk One of the impacts for technical communicators is that the field has always been about explaining things and making sure that it’s explained in a way and using a vehicle that’s appropriate for the audience. A lot of audiences now are consuming content differently. They’re consuming content through handheld mobile devices; they’re starting to consume content through things like Google Home and Alexa and even Siri on phones.

Feldman: The reason user experience writers are becoming more mature as a discipline is really because of apps and that type of experience.

Woelk: Because consumers are consuming content on mobile devices, the information has to be very usable and appropriate for those devices. A lot of technical communication people are moving into [or] at least touching on user experience, on human-computer interaction, things like that, because the way the user interacts with the content is changing so much.

On the gradual evolution of content

Ressaire: One of the biggest changes that I see coming for documentation—or, as I like to call it now, information—is around contextualization. What do I mean by that? In the past, documentation was very linear. Everyone got the same information. What we’re seeing [now], and I fully believe it’s going to become more and more important, is that information is becoming contextualized to the user experience. We’re already seeing that in places like Google and Facebook. We don’t all get the same information.

One of the things we’re looking at in software is how do we contextualize the information to the experience of the user? And [also] understanding that the experience of the user is constantly changing—whether that be their location or their level of experience with the product, it’s constantly in flux. We have to find ways for our information to be dynamic.

Woelk: Some of the work for technical communication is moving into writing for chatbots.

Ressaire: I’m working a lot with chatbots and chatbot platforms. I think it was a Forrester survey that told us last year that by 2024, 85 percent of customer service in the U.S. is going to be handled by chatbots, robots, or virtual assistants.

One of the things I’ve been doing [with chatbots] is talking to a couple of different chatbot companies, a couple of different documentation companies, and saying, “Okay, you need to work on APIs that will help you talk to one another, that let your software talk to one another.”

We created a chatbot [with one company] that basically says, “Hi, I’m the ABC bot, my name is Eddie.” We’re trying to give him a little bit of personality. And he says, “I’m here to help you learn how to use this software.” We’ve got new technology, we’ve got contextualization, we’ve got customer expectations that this bot does indeed understand who they are, and then behind the scenes, we’ve got process.

Feldman: The easiest way to summarize it—and this is a big umbrella term—is micro-content.

Woelk: It’s little chunks of content, which somebody will interact with, and then it will lead them to a different piece of content through artificial intelligence. A chatbot is just an example of how that’s being leveraged right now.

Feldman: You’re producing content that’s meant to live and evolve as micro-content. There are various definitions out there. Just to clarify, some people think micro-content just means the small snippets of text. I consider that micro-copy—just a little bit of UI text here and there—whereas micro-content is meant to be the smallest amount of content that is still a complete source or task or solution.

You don’t [just] publish all of your content into a user guide or a troubleshooting guide or a getting started guide—the content list has evolved, as the micro-components can stand on their own and then be remixed into different experiences as needed. Sometimes that might become like a study guide, but more often that content is going to get injected throughout a user experience.

Ressaire: One of the trends we have seen in documentation over the last 10 to 20 years is something we call multi-channel publishing, which offers single sourcing, where instead of having a lot of different information in different places, we’re trying to put our information into a CMS so that we can actually make our information more consistent and we can publish it to many channels.

Woelk: There has been a gradual evolution over the years in the way writers are working and how they work with content, and there’s been a big focus on content strategy and content experience.

On meeting users’ needs

Ressaire: One of the things I teach students who are learning about technical communication is to develop personas. We’re very familiar with personas in marketing because marketing has been using personas for a very long time to develop content. For technical information, we need to do the same thing—especially if we’re moving towards contextualization. It’s why we’re working with artificial intelligence and deep learning and machine learning—because we can’t figure out how to deliver this information until we can first understand how to gather the contextual information from the user.

Let’s say we’re talking about software. The first time [a user] comes in, the first thing I’m going to do, if I understand that they’re a new user, is [to try to] understand their role within an organization. Maybe they have very limited permissions in the software, or maybe they have very advanced permissions in the software. In other words, within the same company, one user will not see or have all of the same rights and permissions in the software as, say, a manager. In this example, for this user, I would onboard them. I would give them the first thing that they need to know about how they can enter the software, start using it, and very quickly come up to speed and accomplish their goal.

There’s a convergence here that doesn’t [only] affect the information itself, but the whole structure of an organization and how they work together and produce information. We’ve seen a lot of webinars and articles and things in the last few years in our industry that have broken down silos within organizations.

Feldman: You have your tech-com content—meaning your traditional content, with user guides and things like that—on a documentation page. Then you have your knowledge bases that are run by support teams that have the more modular micro-content that’s needed to solve individual issues. All of this content still lives in silos governed by the team that produces it. You can see it—website navigation is often labeled as such. It’s very evident. [But] customers do not care who’s making the content they need. As soon as you’re forcing the user to make a choice to go find the information they need based on a category that you’re defining internally, you’re increasing [their] effort level. They shouldn’t have to think through how you’re producing your content or what the name of the group is or the category of the content that they might need. It should be completely seamless for them.

Woelk: There’s [now] a lot more interaction with customers in terms of how documentation is generated, and you’ll see the roots of having customer-facing wikis or forums. There are a lot of forum-type things where [you can] capture information that customers are providing. One of the reasons that technical communication is so important, and we’ve all seen this, is that designers of products, whether they are programmers or engineers [or what have you], may be able to communicate very well amongst themselves, but they [may not be as] good at communicating to the users of those products. Part of the role of a technical communicator is to bridge that gap.

Feldman: Content professionals are a little bit overly attached to their tool and the way they make content. They’re more focused on how they make content than how it’s delivered. The focus needs to shift away from, “I’m an expert at using this tool,” to, “I’m an expert at understanding how my users interact with my content, and how the content needs to evolve to make them more successful.”

Woelk: You may have a documentation department that turns out those larger manuals and things like that, but [we’re seeing] a lot more integration into project teams, where you [might] have a technical communicator [who] will actually deem whether it’s an agile type of project or something else. That technical writer, that technical communicator, is now part of that team, usually serving as an advocate for the end user, who is going to be using the final product.

On the evolving role of the technical writer

Feldman: You’re going to have fewer of these standalone documentation experts. It’s going to be a lot more collaborative across the organization [when it comes to] how this content gets created. You’re going to have fewer different content teams producing things in their own way.

Ressaire: One of the things that I advocate for is the complete breakdown of silos, in order to produce those products and accompanying information that would truly meet the needs of the users. One of the things we’ve seen a real huge surge in [over] the last 10 years is the API. The API is a beautiful thing to me, because it allows pieces of software to talk to one another.

Feldman: The new persona of the more successful content professional is going to be more and more multifaceted [rather] than hyper-focused in terms of their skill sets. My title at MindTouch is content experience manager. I manage how the content is written, but my title reflects that I’m responsible for how that content is experienced by our users, not [just] how it’s produced. That means getting on board with things like content analytics and mapping that to conversion—a lot more interaction.

Ressaire: This is not a completely new trend. I was working 15 or 20 years ago at Rosetta Stone, which is a language software company, and I was embedded on the engineering team, on the developer team, as a technical writer. I often worked very closely with Support. I was working on both ends—I was helping to actually develop the product, because [as] technical communicators, we consider ourselves user advocates. I was helping the dev team to create good UI. On the other end, I was producing the documentation for it and working with Support to find out what types of problems users were having. We don’t just want to write more documentation to help solve users’ problems, we want to go back to the UI, to the UX, to the product, and make the product better.

Feldman: When I say multifaceted, a lot of it is more about who we need to align ourselves with. I need to become best friends not just with the engineer who is my subject-matter expert, but [also] with the UX designer who is actually dictating how this content ends up getting delivered into the user experience.

Woelk: Part of the role of the technical writer or the technical communicator [is to ensure] that the content is usable and understandable by the end user, and that the end user can do what they need to do with whatever the device, app, or product is.

Ressaire: I think the ideal solution is that all of the barriers be broken down within organizations so that we have better communication, not only between the engineers and the documentation experts, but also between support, which would be after sales, and marketing, which would be pre-sales.

Some final thoughts

Feldman: In the not-so-distant future, I think that all content is going to be written in a way that’s modular and reusable. PDFs as we know them today will be gone.

Ressaire: Companies who are still relying on PDFs to present information really need to move forward quickly or they’re going to get left behind, because information is such an important part of technology. We cannot afford to lose our users because we’re not willing to provide information to them in the way that they are expecting to receive information.

Feldman: The truth is that users are going to have more control over what that content ends up being than the company. We’re going to have to continue to let users dictate what they need, as opposed to the other way around.

About the author

Chris Stokel-Walker is a UK-based features journalist for The Economist, Bloomberg, the BBC, and Wired UK. His first book, YouTubers, was published in 2019, and his second, TikTok Boom, was published in July 2021.


Artwork by

Justina Stasyk


Buy the print edition

Visit the Increment Store to purchase print issues.


Continue Reading

Explore Topics

All Issues