It’s Time for a New Doctrine of Technical Communications

Tech Writer Today’s Integrated Technical Communications column is brought to you by Adobe Systems, Inc. Download a 30-day free trial of Adobe FrameMaker here.

Publisher’s Note:  we continue our discussion on integrated technical communications and future directions for our field with  this guest post from Mark Baker, who blogs at Every Page is Page One, and discusses the need for a new technical communications doctrine.  We encourage you to join the conversation by posting a comment below.

There is little doubt that technical communications is in crisis. The latest testament to this comes from Scott Abel and Jack Molisani in an Intercom article entitled TechComm 2.0: Reinventing Our Relevance in the 2000s, in which they argue that technical writers have to stop calling themselves technical writers altogether. I disagree with them on that point, and I also disagree with them on their title (though I agree on much of what they say in the rest of the article). Tech Comm 2.0 is what we have now, the result of a profound change in technical communications doctrine that occurred in the 80s and 90s. What we need now is a new doctrine of technical communications, in their terms, a Tech Comm 3.0.

Abel and Molisani are certainly correct in identifying the difficulty that tech comm has in demonstrating its relevance to the rest of the company. This is hardly a new problem. As Connie Giordano and Al Martine point out in their article Integrated Technical Communications: A Strategy for Technical Communicators, skimming the Techwr-l archives will show that tech writers have been worrying about demonstrating their value for many years now. Still, I think it is fair to say that, in these days of downsizing and outsourcing, the issue is more urgent than ever.

The Cluetrain Manifesto has this to say about companies struggling to position themselves in the market:

Listen to what your market says you are. If it’s not to your liking, think long and hard before assuming that the market is wrong, composed of a lot of people who just are too dumb or blind to understand the Inner You. If you’ve been claiming to be the Time Company for two years but the market still thinks of you as the Overpriced Executive Trophy Watchmaker, then, sorry, but that’s your position. If you don’t like what you’re hearing, the marketing task is not to change the market’s idea of who you are but actually to change who you are.

Tech Comm has been trying to change the corporation’s idea of who it is, not for two years, but for more like two decades. It really is time to ask if, rather than continuing to try to change what the rest of the company thinks we are, we have to start thinking about changing what we actually are.

Current technical communications doctrine

It is an axiom of business that you can’t manage what you can’t measure. The problem is that actually measuring the business impact of individual action and decision is very difficult and very costly. Separating the contributions that individual parts of the product, let alone individual actions of employees, have on customer buying behavior is virtually impossible. Business measurements, therefore, are done periodically and in aggregate. To manage their day to day operations, business functions develop certain doctrines about product, quality, and process, and manage and measure against these doctrines in their day to day operations. (The debate between waterfall and agile methodologies in software development is a perfect example of a clash of process doctrines.)

Wise corporations will periodically check their doctrines against the marketplace, to make sure their doctrine (their product doctrine in particular) still reflects the reality of the market. But even the best companies can spectacularly fail to perceive the need for a change in doctrine until it is too late, as was the case for North American car companies in the 70’s, or for Blackberry maker Research In Motion in recent years.

Modern tech pubs doctrine was largely formed in the tech boom of the 80’s and 90’s, and it involved a direct challenge to the previous tech pubs doctrine, which was, by and large, a doctrine based on engineers talking to other engineers using formal terms and formal language that presumed a background and training in engineering.

The tech boom suddenly thrust vast numbers of high technology gadgets and software applications into the hands of consumers and ordinary front line workers. Suddenly, technical publications based on the engineer to engineer model simply did not meet the urgent business need to help all those new consumers learn to use the products they had bought. A new doctrine of technical communications was desperately needed.

This is not to say that there was no consumer-oriented tech comm before this time, for it certainly existed. But it was the tech boom that made the information needs of the consumer urgent enough and important enough to successful product sales, that it forced a fundamental change in tech comm doctrine.

The new tech comm doctrine was based on the model of a user with no knowledge of engineering language, no background in engineering, and no interest in understanding the technical underpinnings of their new purchase. This new doctrine saw the user as naive, impatient, and easily discouraged or distracted. This view was well founded in contemporary business considerations. High tech was putting tools that has formerly been used by engineers into the hands of much less qualified workers, and was putting gadgets, computers, and software into the hands of consumers and office workers who had never seen anything like them before.

All these things were new to everybody. It was not like it is today, where there is a technical person in every office and every family, to whom the rest can turn for help when gadgets misbehave. Everyone was a novice. Everyone was afraid of the new tech (even those who were excited about it). The need for customer education, at the simplest and most basic level, was enormous. Good documentation that stated with the most basic of basics and held the user’s hand through all the essential operation of the product was an absolute business essential. You could not sell a product without it. A new tech comm doctrine was born to meet this need.

The previous doctrine did not give up without a fight, however. Despite many complaints about how incomprehensible the old engineering-style documentation was, there were many who felt people should educate themselves properly before attempting to use complex technology and it accompanying documentation. The new doctrine won — the business pressures were too great for it not to win — but, like any revolution, it has its history of battles fought and victories won, battles which enshrined words like usability, minimalism, and information mapping in the heroic lexicon on the new breed of tech writers. Like all revolutionaries, therefore, having spilled their youthful blood in the revolutionary cause, the people who forged the new doctrine of tech writing are often very reluctant to consider the possibility that it may already be out of date.

But it is out of date. It is now as much out of date as the pre-boom doctrine was in the tech boom era. Since the main tenants of the new doctrine were set in stone, three major things have happened which undermine its basic view of the market and the nature of the market’s information needs.

  1. People have become tech savvy. Ordinary consumers and front line workers have no problem using computerized systems anymore. Of course, there are still a few technically naive users out there, but those who remain are the ones least likely to read a manual, and  they are surrounded by tech savvy colleagues and family members who can help them out when needed. (Abel and Molisani say that much of tech comm has become commoditized, but I think that misses the bigger picture: much of high tech itself has become commoditized, and commodities are known quantities that require little consumer documentation.)
  2. The Web has connected everybody. People always prefer to learn from other people, but before the Web, the number of qualified people you could ask for help with a technical problem was often small, forcing you to rely on documentation. Now, however, most people have access to the web and are savvy enough to use it effectively. People can now ask the entire world for help with their specific problem and get a useful and immediate answer most of the time. In the words of the CluetrainManifesto, markets have become conversations.
  3. Everything is networked. In the early tech boom, most high tech products were standalone. This is not to say that every piece was made by a single company; companies often bought components from one another, and needed engineering documentation to integrate them. But today, there is more outsourcing of components (enabled by a global market fostered by the Web) and most products work as nodes in one or more networks, meaning that there are more and more interfaces between components at every level, all of which need documentation.

These three things undermine the basic business presumptions of current tech comm doctrine. The presumptions could be summed up in three propositions about the business value of technical communications:

  1. Documentation is essential. You can’t ship the product without it.
  2. Documentation is fundamental to the user experience. Without it, consumers will hate your product and not buy it.
  3. Perfect grammar, style, and formatting are essential to maintain the company reputation. Without it, your company will be a laughing stock.

 

This doctrine was largely correct circa 1990 (at least in high tech). In 2012, it is largely incorrect. To understand why, let’s look at each of these proposition in turn:

Not every product needs a full doc set all the time

The first proposition is that you can’t ship tech without a full doc set. Yet my smartphone and my tablet both came with a booklet of safety bumph and a slip of paper with instructions for plugging in the battery charger. There are no docs on the devices either. Hardly a full doc set. Yet both products sold enough units to make Steve Jobs very very angry.

This does not mean there isn’t any help available for these products. If I have a problem or a question, all I have to do is Google the model and the issue, and I will find multiple blog posts and forum discussions on my exact issue, along with a selection of solutions, and usually a consensus about which solution is best. There is lots of help. There just isn’t any documentation.

There are lots of other reasons why a product may not ship with a full doc set today. A tool vendor, for instance, may issue the first version of a tool to a small group of partners, or even to a single partner. Their engineers work directly with the engineers of the partner companies to integrate their tool. Creating a full set of consumer-grade technical documentation would only slow down the process. A combination of code comments and emails between the co-operating engineers from each company gets the job done. A later release might need a full doc set, but not the first one.

On the other hand, an aging product that has a broad user base, but declining new sales, may still be updated regularly, in part to keep up with new requirements, and in part simply to drive maintenance or upgrade revenue. But most of the customers are familiar with the product and there is plenty of third party information available, as well as supportive user groups. To continue to maintain a full doc set for this product is unlikely to affect its sales, and so the expense of creating those docs can only eat into its margins.

The doctrine that every product must have a full documentation set from first release to the end of its natural life, is out of sync with modern business realities.

Docs are not at the heart of the user experience

The second proposition, that docs were fundamental to the user experience, made perfect sense when all the tech was new. People couldn’t use the tech without the docs, and what is more, they could not use the docs unless the docs themselves were made much easier to use than they had been under the previous doctrine.

User experience is a hot topic in the business world these days. This is exciting for tech writers, because we have been on the user experience bandwagon for a long time. But not all UX is equally important to the bottom line. You can improve user experience by putting Krugerrands in the Corn Flakes, but if you put the price up to match, the consumer will switch to Wheaties, and if you don’t, your shareholders will quickly be in revolt.

Clearly the UX of driving a Mercedes is better than the UX of driving a Chevy, but more buyers opt for the good-enough user experience of the Chevy at the Chevy’s more affordable price point. UX, in other words, is not an unlimited good — there is only so much UX most people can or will pay for.

So the business question is, when does improving the UX of the docs increase either the price the user is willing to pay for the product (margin) or the number of units that consumers are willing to buy (market share)?

If you said “always”, you are being blinded by an out-of-date tech comm doctrine. If you said “never”, though, I think you are being a bit too cynical. I think the right answer is “sometimes”. But if the answer is sometimes, then the question becomes, “which times?” When, and by how much, do docs affect the user experience enough to affect margins or market share? To answer that we would need a new doctrine of technical communication.

Perfection is not all it’s cracked up to be

The third proposition, that perfection in all the mechanical aspects of writing, presentation, and production is essential for user confidence in the docs and in the company, was clearly influenced by the predilections and education of the thousands of arts graduates who flooded into tech comm in the boom years, but it also made a great deal of business sense at the time.

For tech to cross the chasm (to borrow GeoffreyMooresphrase) it was necessary to assure a skittish public that the gadget or the software they were contemplating was not the product of a long-haired geek working in his parent’s garage, but the work of a respectable secure corporation. High tech companies needed plush documentation for the same reason that investment brokers need plush offices: to assure the public that they were secure, stable, and knew what they were talking about.

To be sure, the concern with the mechanics is often born of the personal peeves of the writers. It is illogical, from a business point of view, to complain that no one knows how to use the subjunctive or the semicolon correctly, and also assert that their incorrect use will ruin the reputation of the company. Your reputation obviously cannot be ruined by a fault nobody recognizes.

But there is no doubt that standards of grammatical purity and presentational elegance are very different on the Web than they were in the age of paper. (The same illogic about standards is sometimes evident when writers decry the state of communication on the Web. People cannot possibly be scandalized by lapses from a standard that they clearly do not embrace themselves.) But I think there is a larger point here, and it is not one about loss of standards or the Web being bad for our brains.

The real point, I believe, is that we have, and always have had, different standards for conversations than we do for publications. The reasons for this are both simple and sound. With a publication, communication is fixed and distributed, without the possibility for clarification or recall. It therefore needs to be very thoughtfully and carefully prepared. A conversation, on the other hand, is immediate and mutable. Ill considered statements can be revoked and unclear points explained. In conversation, immediacy, personality, and frankness are much greater virtues than fixed perfection.

Why this matters is that the web is not a medium of publication, but a medium of conversation. Thought the conversation may take the form of text, it is immediate and mutable, like a conversation, and immediacy, personality and frankness are valued above fixed perfection. The Web is not a publication; it is a conversation.

Even though contemporary tech comm has, if somewhat reluctantly, moved to the Web, it has failed to adapt its doctrine to this core fact: the Web is a medium of conversation, not publication. Thus we see tech writers regularly resisting the incorporation of user generated content or allowing engineers to produce material that goes directly to the web without the writer intervening to bring it up to publication standards. This constitutes not only the application of inappropriate publication standards to the Web conversation, but a failure to respect the conversational standards of immediacy, personality, and frankness. Current tech comm doctrine simply does not get the Web.

Towards a new doctrine of technical communications

The doctrine of a professions focuses on its day to day processes and procedures, and its working assumptions about what constitutes product quality. To form a new doctrine, we have to step back from all the specifics of the current doctrine and focus on the current business problem.

Giordano and Martine, make an admirable start on this with their definition of integrated technical communications:

Integrated technical communications (ITC) is the coordination and integration of all technical communication processes, tools, functions, and sources within an organization to convey information and knowledge relevant to optimizing the users’ product experience.

The only thing missing here is a mention of creating shareholder value. Creating shareholder value is an inescapable part of forming a new doctrine. Without it, one can quickly get back to Krugerrands in the Corn Flakes. But what is important about this definition is the other thing it omits: any reference to publications. This is a definition focussed on conveying information and knowledge to users, not on publishing anything. That has to be the starting point for a new doctrine of technical communications.

That said, I can’t agree fully with Giordano and Martine on the vision of integrated technical communications that they begin to construct on this admirable foundation. Their six high-level processes — analysis, research, content creation, production/dissemination, feedback, and archival — strike me as being too much founded in the current publications-oriented doctrine of technical communications, and too focussed on research and analysis rather than personal knowledge and experience. The new doctrine, I am convinced, cannot be founded on publications or publication processes. It may use publications as a tool, but it is not about publications, it is about communications, and that, today, means conversations.

Abel and Molisani believe that tech writers have to stop calling themselves tech writers and show that they can add value in other areas. I think that may be good advice for the many tech writers who entered the profession under the current doctrine which emphasises language and communication skills over technical skills. They are a product of the contemporary doctrine, and they may not have a role, or as large a role, under the revised technical communication doctrine that modern business conditions demand. It may well be time for them to find some other way to contribute to the success of the company — and in an age where markets are conversations, there is no shortage of demand for their skills.

But I don’t believe that technical communications, or the title of technical writer, is going away. The Web may be a conversation, but it is a written conversation, and writing skills still count for a lot. However, I do think that business realities can no longer be avoided and that a new doctrine of technical communications must now be created.

What will that new doctrine be? I don’t think that any one of us has the perspective to map out a complete new doctrine by ourselves, so I will attempt no more than to suggest some realities that I think the new doctrine must take into account. Three spring particularly to mind:

Docs and the product cycle

The Product Lifecycle at Wikipedia

In an information-rich networked world, there are many source of information on a product. There is no value in duplicating information that is already available, or in providing answers that will be readily forthcoming the moment someone asks the question. But there are still times when information deficits exist that must be filled in order for a product to succeed.

Products, and product categories, have a life cycle. Information availability and information needs vary widely over the course of both the product and product category life cycles, just as prices and margins do. A new doctrine of technical communications needs to focus on those parts of the life cycle where injecting information into the marketplace makes the most difference to sales and to margins. This requires a complete rethink of the place of information development in the product lifecycle.

The technical reference deficit

In my experience, many technology companies have huge deficits in core technical reference documentation. Core reference information has been neglected for years because current tech comm doctrine does not have a place for it. Tech comm resources are seldom devoted to this kind of work because it is considered too technical for many tech writers to handle, and because, under current doctrine, complete suites of plush user-focus documentation are considered essential, and preparing them soaks up all the available resources. (It is sadly all too common for tech comm managers to reject all requests for tech pubs to become involved in any other communication activities in their company because they have no resources to spare from the preparation of the doc set that their doctrine says cannot be sacrificed for any other consideration.)

Yet in a world where each company focuses on its core competence and outsources everything else, where components are sourced from around the globe, and where almost every device is networked in one way or another, the demand for thorough technical references for all these components and interfaces is enormous. And because of the speed of development that the modern market demands, traditional ways of preparing and disseminating this information are inadequate and can be significant impediments to business success in the marketplace. There is a crying need for people who can create this information swiftly and disseminate it instantly. Contemporary tech comm doctrine practically excludes technical writers from playing this role; the new doctrine must make it central to new tech comm practice.

The primacy of conversation

The old tech comm doctrine is publication-based, but most technical communication taking place today is conversation-based. Not only does this affect the way tech comm should think about mechanical purity, it should also change the way it thinks about project scope. In a publication model, publication of the technical documentation occurs at the time the product is released. But in the conversation model, the conversation begins before the product is released, and goes on after the release, continuing until the last copy of the product goes out of use.

Technical communications in the future will be primarily a conversation. Some publications may still be involved, but they will be seeds of conversation; a beginning, not an end. This will profoundly change both the how and the when of technical communications projects. I don’t think the title of Technical Writer needs to change, but we must stop calling the department that employs technical writers Technical Publications. At least rename it Technical Communications, but if you really want to emphasize the point, rename it Technical Conversations. That will really put the company on notice that there is a new doctrine of technical communications at work.

A new type of technical writer

Will there continue to be technical writers, then? I believe so. There is still a great need (indeed, a growing need) for the creation and dissemination of technical information, and most of it will be in written form (for the web may be a conversation, but it is a written conversation). Technical communications will be a more technical profession, firstly because the audience it addresses is already, and will continue to be, an audience largely of technicians and engineers, and secondly because there is no place in a conversation for an intermediary or an editor.

If you are to speak with immediacy, personality, and frankness, it must be from your own knowledge and experience. But precisely because it is a conversation, technical communications will still require communication skills as well as technical skills. It will require a blend of hard skills and soft skills that should make it largely immune to commoditization.

A new doctrine, and a new model of technical communicator,  will arise, and is already arising (as Abel and Molisani’s survey of the state of the job market illustrates) because contemporary business needs demand it. There will be resistance, of course, from the technical communication establishment. Particularly, I suspect, there will be resistance from pubs managers entrenched in the current doctrine. But these barricades will, in the end, prove indefensible. High tech is no longer novel; it is mainstream. The primary medium of technical communications in no longer publications, but conversations. We need a new tech comm doctrine for this new era.

Mark Baker

Mark Baker provides consulting services and training in structured writing and topic-based authoring through his company, Analecta Communications, Inc. (analecta.com). He has been practicing and implementing structured writing since the SGML days, and gave his first paper on topic-based authoring at SGML 95, under the title "Component Based Information Development". His previous positions include Manager of Information Engineering Methods at Nortel and Director of Communications for SGML pioneer OmniMark Technologies. He blogs on topic-based authoring at everypageispageone.com. He is also the creator of the SPFE ("spiffy") architecture for structured authoring and publishing, which is described at SPFE.info, and is working towards the first release of a SPFE Open Toolkit.

Read more articles from Mark Baker

Try Doc-To-Help Today