The Evolution of a Technical Writer – Bringing Documentation Into the Web 2.0 Age

How has technical writing evolved in the age of the Internet? How have tech writers’ jobs changed, and how should they continue to change, in response to new technologies now available for sharing knowledge with our customers?

Prologue: The Dead Tree Society

My technical writing career began twenty years ago, with the design and writing of software training courses for desktop publishing. These were delivered as printed sheets in a binder used in face-to-face classroom training.

The first manual I wrote was for an optical-character recognition software. Soon after that, I co-authored a very technical book (Publish Yourself on CD-ROM, Random House, 1993), which included a manual for Easy CD 1.0 (later named by PC World one of the 50 Best Tech Products of All Time).

The book was one of the first in the world to include a CD, for which I produced a screen-readable, hypertext-rich version of the text (the CD also contained a demo version of the software). This early experience demonstrated the power and flexibility of electronic texts, but we still had to deliver them on physical media.

Moving It Online

Between 1992 and 1995, I wrote manuals and software-based help for several versions of Easy CD and other CD recording software. Paper manuals were (and are) expensive to produce, print, and distribute. Even “online” help, when it’s deeply hooked into the software (e.g., context-sensitive help for each dialog box) could not be rev’d any more frequently than the software.

As we entered the Web 1.0 age, customers’ expectations of company responsiveness increased, and these old, familiar processes were no longer fast enough. We needed a way to provide customers with updated and expanded information about our software, on demand (in response to FAQs and newly-discovered bugs as they arose), and at low cost.

The worldwide web came to the rescue. When the small software company I worked for was bought by Adaptec, I had pages ready to post on Adaptec’s new website. I soon found myself responsible for the busiest (though not the largest) section of the Adaptec site, which eventually brought in up to 70% of overall traffic – clearly, we were providing information that customers wanted.

Usability

Meanwhile, a separate but converging trend in the industry aimed to improve software usability. After years of slaving over manuals, I realized that, for most users, RTFM is a last-ditch solution. At least where consumer software is concerned, most of us just dive in and start using it, and only look to documentation when we can’t figure out something from the UI (user interface). Users increasingly expected that they should NOT need to open a book or help file, except maybe when using advanced features – a reasonable expectation, I think.

I further observed that, when a software process or feature is difficult (as opposed to complex) to document, this usually means that something’s wrong in the software design. I began working closely with the engineers, initially during beta testing, then earlier in the design phase so that I could try to head off UI problems from the start, rather than be told later: “We won’t have time to fix that til the next release.”

And I worked directly on the UI, writing and editing text strings for dialog boxes, etc. This was obviously a job for a tech writer: the clearer the messages onscreen, the less I would have to explain in the manual.

Collaborating with the Community

Around 1993, I had begun to interact daily with customers online, and soon learned to value their knowledge. No QA (quality assurance) or tech writing team can spend as many hours with a product as a large pool of users will collectively spend with it, nor can an internal team hope to duplicate all the diverse situations in which customers will use it. When we tap into what customers know about our products, both sides benefit.

In the mid-90s, I was an active participant on Usenet forums, answering questions where I could, keeping an eye on hot issues, and conveying customers’ knowledge and issues back to the company. (NB: By late ’95/early ’96 I had handed off my manual-writing job.)

In 1996, I launched a moderated, email-based discussion list which fulfilled the same functions, but in a more controlled and congenial atmosphere. The same concept is seen today in discussion forums run by companies on company sites (which may not be moderated or even monitored).

My role as a tech writer in these virtual meeting places was to work with users to find answers to problems, then to “pretty up” and post that information to the website and, in the longer term, write it into the documentation and/or take note of it in future product design.

I did not originate all this new material (that wouldn’t have been humanly possible!), but my deep knowledge of the technology and ability to write about it in layman’s terms made me ideally suited to fit this new “outside” information into the bigger picture – I was now more a knowledge editor and manager than a writer.

Where I did create original material, it was usually in response to customer FAQs and other expressed or observed customer needs. By staying close to customers and interacting with them daily, I kept a finger on the pulse and knew what they needed/wanted, sometimes before they knew themselves. I considered myself a conduit for information between customers and the company, translating from user-speak to engineer-speak (or boss-speak) where necessary.

New Tools

In the six years since I quit my job with Roxio, the technologies available for online communication and collaboration have, of course, moved on. We now have two very powerful new tools: blogs and wikis. How should we use them, and other new tools that will doubtless show up in the future? That’s a topic for another article.

Your thoughts? If you’re a tech writer, how have you seen your role evolving, and what do you anticipate for the future?

Leave a Reply

Your email address will not be published. Required fields are marked *