Bolg - The Chris Blanc Weblog

(Note: This is from User Advocacy blog. We’re publishing it here because it’s cool and we have permission from the author.)

Summary: Once a necessary part of product deployment, technical writing is slipping to an afterthought. Why that’s happening, and how to re-define technical writing to both overcome it and deliver better value, by experienced technical writer, developer and project manager Chris Borokowski.

A human being should be able to change a diaper, plan an invasion, butcher a hog, conn a ship, design a building, write a sonnet, balance accounts, build a wall, set a bone, comfort the dying, take orders, give orders, cooperate, act alone, solve equations, analyze a new problem, pitch manure, program a computer, cook a tasty meal, fight efficiently, die gallantly. Specialization is for insects.
-Robert A. Heinlein

Among technical writers, the state of the profession is a form of contention in itself. Many argue that assuming change is afoot is to knuckle under to the steady stream of buzzwords and fads that make a few venture capitalists rich while everyone else hits the job boards again. A growing faction of otherwise sceptical writers are thinking instead that transition is upon us, and will reward those who adapt.

To understand this change, we need to track the development of technical writing.

Originally a bizarre hybrid between psychologist, journalist, and instructor, the technical writer compiled scattered notes written by engineers and converted them into manuals that normal people could read and understand. This allowed the product-buying public to use technology with which they had no familiarity.

Technical writing through the 1950s and 1960s followed this pattern. Users were expected to have a high school education including some math and science, so much of the job involved explaining specifics in terms of the general skills with which users were more familiar. Gadgets varied widely and so the writer served an essential role, translating engineer complexity into end-user clarity.

With the transistor revolution of the 1970s, two crucial changes occurred. First, the computer migrated from the machine room to the desktop. Second, high schools got more lenient at the same time users became more acquainted with television media. This new generation were shaped by seeing machines used before understanding the principles behind them, which laid the ground for the interface revolution to follow.

On the heels of those developments, a second computing revolution occurred in the late 1980s and early 1990s. Both the graphical user interface (GUI)-based operating system and the world wide web took existing technologies and put them to new use. This usage redefined the comput from being being a calculating machine to an information browser. This role shift entailed thinking about interface in user-centric contexts and resulted in both these revolutions.

Usage exploded since the layperson could now interact with a computer as they would a video game, vending machine or automated teller. This in turn spurred a network revolution. Since the computer was viewed as an information browser, it needed connections to information, so the network became the computer. These influences caused the computer to become increasingly powerful, standardized and ubiquitous.

The standardization affected technical writing. Digital technology exists within an environment designed by the machine, and it makes sense to have single pieces of software handle functions so commonplace they should be standard. This means that, unlike physical technologies, digital machines have a language of interaction which makes most tasks similar in the actions they have in common.

Newer generations of users come to expect this standardized language, and that they can pick up a video game, computer program or phone and figure out the basics of its function with a few minutes of play. They may not have the background in physics, math and electronics that previous generations took for granted, but they do not need people to explain standard interfaces.

Now that the internet age has boomed and rebirthed itself, technical writing struggles to adopt this new role. Complexity has increased, but so has standardization, which means the userbase is well-informed about generalities but not specifics. As the audience has more tasks of a diverse nature, thanks to this efficiency boom, they expect specific knowledge distilled into digestible fragments for quick use. The job of the technical writer is as a result growing and shrinking at the same time.

What characterized technical writing during the early digital years was what we might call a WTFM mentality, for “write the fantastic manual” (or words to that effect). When software or hardware development was done, the tech writer came in on contract and produced a manual, then vanished from the process except for occasional updates. The task was to produce the manual as the last task before shipping.

With the change in our society brought by digital technology has come a change in what the fantastic manual might be, both in form and content. In the 1930s, an egg-beater was a separate tool from a mixer; in the 1950s, they were interchangeable attachments to a motorized mixer base; in the 2000s, they are different rotation patterns programmed into a mixing unit which hooks up to the network, serves a web page of usage statistics, and probably stores recipes to boot.

The way our users read documentation has changed as well. People now are as likely to read the manual on a computer as on paper; in the future, they will be reading it on phones, video screens, e-ink tablets or have it scroll across their forearms in LCD tattoos. Since they know the basics of our networked gadget world, they are less likely to read the manual linearly, and even when not in a hurry they start by looking up terms, skip chapters, and skim.

Technical writing has adapted with three fundamental changes:

1. Task-oriented writing. Instead of describing the parts of a system, we walk the user through tasks and explain technical knowledge incidentally.
2. Single-sourcing. Write-once, read many; we write in small blobs which can be reorganized for online help, web help, printed manuals or marketing.
3. Plain English/Simplified text. We describe the interface, not theory, using code-like patterns of if-then language and action sequences.

The first launches users into a technology by giving them a basic task and building on that knowledge. The second breaks writing down into interchangeable blobs, like note cards, that can show up in manuals, online help, marketing and web site FAQs. It granularizes writing and makes it easier for a user looking up concepts in an index to understand them, but removes much of the emphasis on text flow.

The third simplifies writing into formulaic, code-like language which emphasizes parallelism between different tasks. The first attempt to achieve this, Plain Language, distills the host language into a few thousand words and a few hundred phrases so readers can easily spot parallels between similar actions. The second attempt, Structured Language, rigidly scripts procedures in a logical format that resembles computer code. Although neither has caught on broadly, elements of both have now been integrated into technical writing as practiced at the cutting edge of the industry.

These modifications to the skill of technical writing since 1987 or so have not changed the basic attitude of the WTFM mentality. Instead, they have prolonged its life by upgrading WTFM instead of changing course. However, to a public increasingly acquainted with the similarities between computer-based tasks, WTFM does not provide the depth of information they need, so instead they buy third-party “power user” books to fill that need.

The profession is slow to change. Beyond inertia, technical writers have bumped themselves up to a “professional” salary over the past four decades by WTFMing quickly and frequently. If you want to make it big as a technical writer, the theory as popularized in books like “Making Money in Technical Writing” by Peter Kent goes, become a contractor and rush like a fiend to write as many fantastic manuals as you can in a year.

In the past, that approach worked because much of the manual comprised general introduction or loosely-concealed translation of engineer notes. Changing market information suggests that trend has run its course. When the basics of technology are known, it is easier and cheaper to have an engineer type up notes and hire a college student to format them. As we have made writing more accessible, we as technical writers have become less essential.

Opportunity for future technical writing exists in the dual role of technical writers. We unlike every other role both understand the product, and see it exclusively from the point of view of a user. The shifting market has provided room for this skill to add value not just to the product, but to the company that produces it.

Technical writers do not produce income-generating products. We reduce costs by eliminating confusion that would otherwise be kicked along the line to the technical support personnel, and we increase brand strength by making customers more satisfied with their product purchase. On the year-end assessment, there is no way to prove technical writer return on investment. Over the lifespan of a customer however we build loyalty and increase profit margins.

For most users, technical writing is the first point of contact they have with a product and the experience that defines their perception of the company that made it. After they unwrap the software or hardware and start playing, their first question or doubt will send them to the manual or online help. This first impression of “brand identity” defines what they perceive about the company, how well-organized it is, and how committed it is to its customers.

A manual or help system that communicates quickly without leaving out vital contextual information, which saves time when problems arise, makes a good initial impression that lasts for the life of the product. Similarly, a product with a quality visual design communicates organization and competence. As the example of Apple computer shows, making products look good, with clean interfaces and quality documentation, creates an initial impression that allows users to overlook other shortcomings later in product life.

For more companies to gain this brand identity, without having to hire a small army of other people, technical writers can be the deciding factor. Since unlike all other roles in production, technical writers think about the product exclusively from a user-centered perspective, we explain it in the language of the user, and apply our knowledge of user psychology to break down raw information and introduce it in the right order to be understood.

In production, roles define focus. Programmers concentrate on making the machine produce predictable results. Project managers try to keep the team organized and on schedule. Artists create visuals. Interaction designers script interfaces and study user response. However, there is no role which from product design to completion remains focused on how the users make the technology work to accomplish tasks, except the technical writer, by the nature of our need to explain the product in those terms.

Here is an unrealized opportunity. We can WTFM and remain in a silo called “technical writing” while growing rapidly less relevant, or we can take on an additional role and make ourselves vital. We would be moving from “one way” thinking of explaining technology to users, to a “two way” view in which we both explain technology to users and explain users to technology. This would make products appear more organized, and raise brand value.

Our future is cheap information. Already the internet is awash in blogs, newspapers, forums, mailing lists and other forms of information. Where when technical writing began information was scarce, the question now is how to filter valuable information from the flood. The killer app of the last decade has been the search engine, but the weakness of search engines is that they cannot separate the relevant from the irrelevant based on complex criteria. For now, it takes a human to do that.

Documentation has become omnipresent but universally criticized because most of it is not helpful. One reason for this is that the technical writer usually has minimal input back up the chain of command, so when they encounter something unexplainable or illogical, there is no recourse but to document vaguely. Even more, since the WTFM mentality encourages employers to pick up a technical writer at the end of the project only, most technical writers find themselves sitting down for two weeks with a product before they have to start making reams of text, and quality is affected.

In the cheap information future, that kind of documentation is less worthwhile. The generally bad quality of documentation which came with software in the 1980s and 1990s spurred a huge market in “best practices” books, most notably from O’Reilly and Associates, which described not only how to use an application but how to use it well. They gave more information than manufacturers would by assuming users would be more aggressively seek power users tasks, and that teaching all users best practices would not leave any in the dark.

To compete in a future of cheap information, we need to change our role in two major ways:

1. Best Practices. We must champion “best practices” user-computer interaction by emphasizing the most powerful, not simplest yet leaves out details, way to do a task.
2. User Advocacy. As part of our “two way” communication between user and product design, we must not only explain product to the user, but explain user to the product and the team that makes it.

Every software product lies between two points: the people using it, and the goal of using it. A word processor exists to get its target audience to be able to accomplish a range of tasks without significant confusion and frustration. Not surprisingly, word processors come in different flavors for different levels of experience and specialization.

User advocates want to simplify and make more effective every product we touch, and produce simpler and more effective documentation for it. Our goal is to destroy confusion and ambiguity. We’re also UI creators, but too ofen, UI design is contingent upon quality product design — if the product is coded around the wrong processes for its intended use, or its design is ignorant of common methods, it will be awkward to use in the way it is most commonly used.

In this new role, we’d be part journalist, part communicator, part trainer, part project manager, and part interaction designer and user advocate. This is to the benefit of writers, as we get to spend the entire product development cycle getting to know it and get a more justifiably necessary and lasting role, and companies, as they get several roles in one.

The best technical writers I know are the ones who happily roll up their sleeves to dive into an unknown situation and get dirty. They are word warriors with the goal of saving that user who at midnight, with something done by dawn, needs to read one paragraph, understand it and move on so she can return home to her family. These technical writers are commandos in planes far above the earth, grabbing their laptops and chutes and leaping out the roaring open door.

This aspect of technical writing will never change. To enjoy confronting the baffling, making it clear, and teaching it to others is the eternal personality type of the person who will become a technical writer. Where this will change, in our new user advocate sense, is that we will do so over the life of the product and will channel information in both directions.

The flip side of this change is that we can also become a part of the development team that ensures the interface is consistent, the application works from a user’s point of view, all of its parts work correctly and the experience confronting the user is one they will want to return to. We will be instrumental in communicating application to user, and user to application. This is an indispensible, professional role, while showing up to WTFM on contract no longer is.

Support for this idea has come from those trying to make development more efficient. Steve McConnell (author of Code Complete) proposes early draft user guides as a replacement for requirements specifications. Many startups use writers from inception to document internal methods and procedures, and in the process have employed them as software testers, quality analysts and even interaction designers because of their dual specializations as experts in the software and advocates for its users.

The future for technical writing may be bright, and also dark, as any transitional time must be. We have to let go of the old, and make a big push to accept the new, and then we will find ourselves in a better place. When we do this, we will be able to fit into the future needs of our industry and market ourselves more effectively, creating a longer-term role for our profession.