Search results

What Users Don't Care About

by Tom Johnson on Jul 11, 2009
categories: technical-writing

It seems most of the conversations in our industry today revolve around value. If you go to, the large graphic at the center of the site says "The Value of Technical Communication." (Given the recent events in the STC, to me the graphic really reads, "The value of the STC organization.") At any rate, technical writers have been talking about demonstrating value to employers in quantifiable ways for years.

The value of technical communication
Technical writers frequently talk about value, but much of the value is invisible to users

Part of the problem in our attempt to demonstrate value is that our help deliverables look the same as they did 15 years ago, more or less. Online help and a PDF manual. It's not a format that engages users. The web marches forward with innovation after innovation, while the technical communicators are figuratively hunched over keyboards, staring at CRT monitors, wearing 1950s horn-rimmed glasses, typing away. At times it seems the technical writer is a relic of a past tradition, a figure barely hanging on to the rapid pace of technology in the 21st century. Or so it would seem.

Although that's the general impression, actually technical communication has had considerable innovation lately. DITA has provided an advanced XML architectural standard for single sourcing that all technical communicators can implement. Even putting aside DITA, single sourcing technologies with help authoring tools have become more common. The old method of copying and pasting to produce multiple deliverables is a primitive practice no longer typical. We've moved into an age of efficient authoring. We can now generate seventeen deliverables from just one, original source. Brilliant!

But whatever methodology has changed in our creation process, the value of our industry's innovation only trickles down to the user, and in an almost unnoticeable way. You may have single sourced your documentation from a large snippet library, breaking up your topics into granular chunks that you're cleverly reusing through your topics, and pulling it all together with conditional builds. But to the user, it's the same old online help and PDF manual.

The user could care less whether the PDF manual is single sourced. Keith Anderson (on Twitter, @suredoc) writes,

I personally believe you can argue the merits of DITA or single sourcing all day long, but the dirty little secret of our industry is simply that users don't care. They just don't care. They do know how they want information and will consume the information in ways that are comfortable or familiar to them ("Sheep, Chaos, and User Experience").

In other words, it doesn't matter to users how you created the documentation. What matters to them is what you create. We have a somewhat similar policy at my work. It doesn't matter whether you work 20 hours or 80. You just have to get the job done. Our CIO even says we can leave to go watch our kids' soccer games at 2 p.m. if we want, as long as we get the job done. (He doesn't mention that it's nearly impossible to finish all your work.) But the focus is on the output, the deliverables, not the clever or cruel process we endure to create them.

Here's another example. Did you happen to read Richard Hamilton's Managing Writers? It's formatted in Doc Book, did you know? Doc Book streamlined Richard's printing process, enabling him to stylize the format in different ways without altering the source. He can print a news article format, a booklet format, and a book format from the same source by just altering a stylesheet. He can also generate the content as HTML, ePub, CHM, or PDF without any additional work.

Despite the innovative format, to most of us who read it, it's still just a book. It looks like all the other books on our shelves. I think most of us, in reading the book, might admit that we don't really care how he created the product (except from a professional curiosity perhaps). Our primary purpose is in the product itself, the content, not with the way it was made. I don't really care if Richard stayed up past midnight every night for two years writing the book, or if he wrote it on the bus, or whether he piecemealed from a private wiki, or published by typing with two fingers on a netbook sitting in a café in Italy while eating plum pastries. What I care about is the end product.

Because users value the product rather than the process, and tech comm's innovation has been in the process, technical communication comes across as stagnant, without innovation, and stuck in the past, while web technologies march forward. The evolution of the web, from static pages in primitive HTML to rich, audiovisual, dynamic content you can interact with by commenting on, subscribing to, trackbacking, aggregating, and mashing up demonstrates tangible progress. It's an advancement in value that you can see and feel in every way, unlike the invisible advances in tech comm.

The frustrating part is that innovation in technical communication—however invisible—does actually benefit the user in a number of ways. According to my colleague Paul Pehrson (@docguy on Twitter), because of DITA and single sourcing, users now have more consistent documentation. Previously, with the copy and paste method, multiple deliverables would invariably be out of sync—updates would be made to one but not the other. Copying and pasting would also exhaust technical writers, and last minute changes were a nightmare.

Now with single sourcing, synchronization issues are no longer a problem. Last minute changes can easily be accommodated. Topics in multiple sources are the same because they're generated from the same source. Translation costs are also reduced.

Because of single sourcing, we can also provide more custom, role-based guides. Rather than delivering one enormous reference manual, we can deliver smaller guides for each role. And we can provide all of this information more quickly, with fewer resources producing it. One person can really generate 17 guides, and even update them nightly through an automated build process each time he or she makes a small change to the content during the day. The reduced time decreases the cost of the product overall, making documentation both cheaper and more accurate.

Still, despite these advancements, the user still holds a manual in hand and thinks nothing has changed in decades. This is perhaps the flaw of DITA: no noticeable increase in value in the deliverable. In fact, the plain formatting and generic style may even appear to be a decrease in value. Without any tangible, immediately felt benefits to the user, the deliverables seems stagnant and lacking innovation. It's a misunderstanding, though—somewhat like the poor, overworked employee who puts in 80 hour work weeks but has nothing extra to show for it.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.