By Barry Grenon
At a company I used to work for, my boss once told me about a conversation he had with the company’s CEO. My boss had been looking to get more money for our department so we could get our docs online, when the CEO looked out into space, disengaging from the conversation. “You know, when people look at our documentation,” the CEO said to him, “I think they often feel just a little bit … sad.”
I’ve heard a few potshots taken at “the docs” over the years. “Nobody reads the docs,” for example, is probably the most common, although Web analytics show that this is false. Documentation is an easy target, and a lot of the criticism it attracts is unfair. Or fair, but misdirected. For example, I have often thought that you could probably “read” a company’s internal dysfunction by looking at how the docs are put together; the docs are a map telling you which departments are talking to each other, which aren’t, and so forth. Inelegant, over-complicated software under the hood shows itself in the help file and knowledge base, and complaints about “the docs” are often complaints about the product itself, shooting the messenger, as it were. Most of these criticisms are taken in stride, but it was what this CEO said—that the documentation makes people feel sad—that stuck.
I think I know what that CEO meant: the sadness of looking over thousands of pages of content, and knowing that something is not quite right. That there is too much detail where there doesn’t need to be. That things do not cohere where they should. That this mediocre output represents hundreds of thousands of human hours squandered on content that, to a large degree, is merely “better than nothing.” Content that does not delight.
Technical writers may be naturally suspicious of the idea that documentation should delight. And for some industries—nuclear power, for example, or airplane assembly—the idea makes no sense at all. But I maintain that a well-made thing, when it does what it needs to do very well, becomes an aesthetic experience, and hence delightful. I would also wager that aesthetics and cognition are more closely coupled than we suspect. A better-looking airplane assembly manual, with sharp photographs, clean page layout, and an elegant use of white space, might actually prove easier to consume, and possibly—maybe even measurably—safer for that industry. We are human beings who use technology, after all, and when we put out content that sounds like it was written by a robot for a robot, we are not helping human beings understand things. Which is the job, isn’t it?
The software industry is a little different, I think. For any industry with technical content that touches customers—enterprise customers, business users, random Web consumers, whomever—where the documentation is understood to be a customer touch point, it feels like there is definitely a new expectation being put on writing groups—namely to make better, more human content. My sense is that the folks putting this pressure on technical writers don’t know exactly what they want. They want us to make content more visually compelling, the writing style more personable, and everything simpler, cleaner, and just better. In response to these demands, I maintain that most of us writing folks don’t know what to do. All of our conferences, keynote addresses aside, talk mainly about the mechanics of running of the show: how to manage content more efficiently, how to reduce costs to do more with less, how to make our writing lives easier in terms of handling the complexity of localized content, re-usable content, or writing for a global audience. These are all of the straightjackets that make us think and write like robots. But mostly, it’s about reducing costs, or as I’ve heard it put, remaining invisible. Reducing costs, however, is not a job, and remaining invisible will not help us keep our jobs. We need to talk less about managing content—that necessary, albeit complicated evil—and talk more about the content itself. Or what we really need to be talking about is sex.
Documentation Is Like Sex
An engineer I work with called over to me in the lunchroom one day. “Barry, I got one for you,” he says. “Documentation is like sex: when it’s good, it’s great. But when it’s bad? It’s better than nothing.”
To me, the element of surprise in this joke was the idea that he thought that documentation actually could be great. In my own travels online and otherwise, it has been my job to figure out how to make my latest company’s content better, and I have seen some great content. A lot of it is developer content, such as API docs, written by developers for developers. But then there’s the Web.
I sometimes think that the Web has become a third technical documentation. Between forums for every hobby under the sun and how-to videos on YouTube, we are all technical writers now. And it often seems that some of the amateur stuff is more helpful than the professional docs. Amateurs seem to default to simplicity and screenshots. Technical writers seem to default to complexity, an overwhelming and sometimes unnecessary completeness, and they usually include no screenshots due to internal (and numerous) maintenance considerations.
I’m intentionally being provocative. There is plenty of good, interesting documentation out there, and companies that get it. In my opinion, though, I think the best technical content is being written by developers—software engineers with a good command of the language and good personalities. I think there are three reasons for this:
- Software engineers design their own platforms. Unconstrained by a towering edifice of content, they make nice UIs for their stuff. They know how, and they just do it. It’s better. Death to tri-pane help!
- Developers write like human beings. They say things like, “Now be careful with this next part, it gets really tricky.” I consider this a helpful phrase—it lets you know that you have to pay attention, and it mentally grounds you to do something. I have never seen a technical writer phrase a sentence in this way. Instead, technical writers default to a formal style that seems to be written by a machine (and one day, if we keep it up, it might be). There is a style choice in this, an effort, I sometimes fear, to appear smart and technical. As soon as one starts thinking about writing professional content, instead of just helping another human being accomplish something, the style seems to stiffen. There may be a bit of reach involved—writers trying to show that they have the technical chops for the job by writing intelligently, but perhaps too complexly, about the tasks at hand. Developers, on the other hand, who live and breathe technical and do not suffer from any insecurity on that account, are fine with making things sound breezy and simple (maybe they just don’t think about it too hard). Considerations, such as grammar, absolute accuracy, comprehensiveness, localization, second-language user considerations, plus a host of other “professional” concerns are less important. Is it a sustainable model? Probably not. For every good example of a developer-written API, there are probably 10 atrocities that never made the listsicle. But it can’t hurt to look at what our technical users point to as good content and learn from those naïve models.
- Developers, for the most part, don’t have to manage content. They don’t worry about translation costs. They don’t worry about single sourcing to multiple outputs. They don’t struggle with partitioning content into discrete chunks that can be repurposed across a complex product suite. They don’t have a million tasks in the background, the kind that unskilled technical writers take refuge in, hoping that “reducing costs” will keep them employed for the length of a career. Believe me, I understand the background sludge that prevents good writing teams from producing great work. We are shackled, in many cases, by the limitations of the tools and the trade-offs we face between making content that delights our users, and making content that we can actually maintain.
We Get the Tools We Ask For
The technical writer is not to blame. It’s not our fault the content is so mediocre. It’s not even the fault of the vendors that supply our tools. Dealing with all of this content requires—I suppose—complex tools. Look at the job boards. Tool requirements for technical writing jobs are both long-winded and terrifying. Tool proficiency often takes an inappropriate priority in the hiring process, making it difficult to hire, for example, the legions of journalists fleeing that collapsing field, who have a lot of value to add to ours. Tool complexity makes it hard to curate content drafted by other people—eager non-writers who have so much knowledge to add to the corpus, but who can’t or won’t use our platforms. Tool complexity turns technical writing departments into bottlenecks, with whole countries of excellent information languishing on Outlook Exchange servers and cheat sheet .txt files scattered throughout a company. And the tools do not focus—since we, collectively, also do not focus—on the customer experience.
Vendor tools do great things. We all know about them. But the great things that they do are centered on solving old problems of managing content and reducing costs, not the new problem of delighting users.
What would delight our users? I have some ideas:
- Increasing the visual component. Vastly. I believe that we should invert the relationship between text and image, so that we choose our key images first—the right screenshot, diagram, screencast, or clickthrough tutorial that best explains a task or concept—and choose text to support that visual component second.
- Writing like a human being, to a human being, since human beings are what we are. Plain language principles are a good start.
- Using judgment and finesse when it comes to setting the level of detail. All technical writers, especially writers of GUI-based software, should know that writing step-by-step instructions is not supremely helpful for people who are mentally taxed, and who are already overloaded with information. Worse, if all you are doing is transcribing the relationship between a button on the screen and how it reacts when clicked, there are robots already capable of doing this for you. Use some judgment and finesse to keep the artificial intelligence at bay.
- Refocusing our industry less on the mechanics of maintaining content and more on the look, shape, and feel of what our users interact with, primarily, the Web page. Notice the absence of the words DITA or XML in this article.
- Dropping the ambivalence and writing for the Web. Optimizing for the Web. If you can’t optimize your content for the Web because you need to keep it in a special condition so that it can be easily outputted to other formats, then you may have too many formats. If you are sacrificing your Web content for the sake of keeping PDFs available to satisfy the handful of throwbacks that still love them, then you are failing the 80/20 rule. Nobody reads PDFs, even when they say they do.
- Avoiding content re-use. Reducing costs is not a job. Doing the same thing twice is stupid, no argument. But writing in such a way that a given chunk of content works equally well in different contexts can often result in content that has no context, becoming inert and useless. You can try adding in variables and conditional text so that the dream of re-using a given piece of content in two or more places at once comes true, but this approach quickly turns to inefficient, complex spaghetti. “Copy, paste, and rewrite” is not always a bad idea. My guess is that for certain industries, and for very specific use cases like 40 slightly different Toyota Camry manuals, these re-use strategies are vital. But for most software documentation, the concept is oversold. You can tie yourself into knots trying to make it work. Who cares? It’s not that important.
- Hiring someone on your team who can customize HTML and CSS. You can use any vendor tool out there to decent results, I believe, but most do not pay close attention to that important customer-facing “last mile.” Let a skilled Web developer spend a week or two customizing your platform’s default CSS output. It is probably the cheapest way to increase user satisfaction in a hurry. I’ve talked to many tool vendors at conferences the last few years. They don’t know why we keep taking their default output and pushing it to the Web, but that seems to be what most groups do. If you don’t have the skills on staff, you may have no choice.
- Asking end users what they need. Vendors, don’t ask writers and doc managers what we need from your tools, ask end users—the consumers of our documentation—what they need. They are not mythical creatures. They do exist—I’ve seen scrolling lists of all their IP addresses in Google Analytics. For example, the number one request, in my experience, has been for more screenshots. Why is there no feature for automatically updating screenshots when a GUI updates? There are hacks for this online, and if we make this a robust feature, a method for updating screenshots, screencasts, and longer videos automatically by running against the latest product GUI, we may see an explosion of more visual content on our documentation websites. Please, help support our multimedia efforts!
- Making a connection with users the first priority. Vendors, writers, video makers, diagram designers, all of us have to make a last connection with our users, figuring out how to help them understand the things we are asking them to do, in as pleasant a way as possible. That is where we add value. That, after all, is the job.
Barry Grenon is a senior publications manager and information architect at Genesys, a customer experience software company recently included in GlassDoor’s Top 50 Places to work. Barry leads the team that builds and maintains their custom documentation platform, docs.genesys.com. He is a long-time technical writer, with a background in creative writing, including an MFA, and publications to his credit from that other life. In techcomm, Barry’s interests are in content engineering and UX and how the two can work together.
