Are Docs a Responsibility or a Business Asset?

By | 2012/01/09

Do we write documentation to fulfill a responsibility, or to create a business asset? Are we striving to meet a set of requirements pronounced by either convention or regulation, or are we striving to increase corporate revenues and contribute to shareholder value?

The question is provoked by an interesting discussion with Jonatan Lundin in the comments on Tom Johnson’s post Using Tags to Increase Findability. (The discussion has virtually nothing to do with using tags to increase findability — sorry Tom!) Jonatan’s position (if I have understood him correctly) is that tasks can be divided into product-centric  and organization-centric, and that documentation should stick to covering product-centric tasks and not touch organization-centric tasks. My position is that the user’s task is to use the product’s features to meet the organization’s goals and that if we are going to produce task-oriented documentation, therefore, we cannot ignore the user’s business domain.

The move toward task-based documentation is of long standing. To borrow a phrase from JoAnn Hackos, it is broadly felt that we “have to stop documenting the product and start working for the user.” This is more than a shift in style, I have come to realize, it is a shift in our view of the responsibility of tech pubs. Curiously, I think the shift is not towards a greater concern for the customer, per se, but a shift towards seeing content as a business asset.

When I started out in tech writing, it was pretty clearly understood where the boundaries of our responsibilities lay. Our job was to document the product, the whole product, and nothing but the product. What if the user needed to use our product with another system? Not part of our responsibilities. We don’t document anybody else’s product, and we don’t document public standards. If we didn’t build it, we didn’t talk about it.

On the other hand, we did not ask much whether people really needed some things documented. If it was part of the product’s behavior, we documented it. I took over one user manual that told the user that if they did such and such an operation, the phone would emit a tone of so many megahertz for so many milliseconds. I changed it to “the phone will beep”. But today I would assume that the customer would hear and understand the beep for themselves. You don’t bother documenting interface conventions that everybody knows.

In those days, documentation’s role was defined essentially as a responsibility. You had a responsibility to document your product, so you documented it. You had no responsibility to document anything outside your product, so you didn’t talk about how your product worked with anything else, and you did not make any assumptions about what the reader was using the product for, or offer them any help with their task beyond describing the features of your product.

To have your job defined as a specific responsibility in this way makes life easy. You can measure pretty accurately whether you have completed your task satisfactorily. 37 features. 37 feature descriptions. Check. Is the user able to get their work done easily? Maybe. Maybe not. But you have fulfilled your responsibility to the user because you have documented all 37 features.

We might imagine that users were frustrated by this approach, but I don’t think they were, in general. I think they accepted the same notion of the limits of the responsibilities of vendors that writers were assuming in their work. Yes, falling into a gap between one vendor’s product and  another could leave you in an information limbo and force you to do a lot of work to figure stuff out, but that was an accepted part of life.

My theory is that it was IBM’s decision to release the PC architecture that led to the breakdown of that longstanding cultural convention, which was actually already underway when I started in tech writing. Suddenly, people were buying a computer from one company, peripherals from another, an OS from a third, and applications from half a dozen more. They expected all the combinations to work, and they were no longer satisfied when each company blamed the other company’s products for the failure of the system to work as a whole. Interoperability of hardware, operating systems, and applications became a business crisis, a point of extreme customer pain and frustration.

Since then, people have only increased the extent to which they interact with systems rather than individual products. They no longer think in terms of the product working or not working, but of the system working or not working. Vendors have to take responsibility not only for making sure people can use their  products, but for making sure they can use the system in which their product operates.

This crisis broke the old boundaries of responsibility, and ushered in a much more pragmatic consideration: customer satisfaction and customer retention in a world where customer satisfaction was based on their whole experience. User experience became an ever more pressing business concern, and the old boundaries of responsibility became  irrelevant in the face of the demand to make the entire customer experience better.

Thus the objective of technical communication becomes not to fulfill a responsibility to thoroughly document an individual product, but to enhance the user experience of people who bought the product. If parts of the doc set are not making any significant contribution to the user experience, trash them. If enhancing the user experience means going beyond the boundaries of our product and its features, that is what we must do.

I frequently mention my time with OmniMark Technologies, and my experience there provides a perfect example of this issue of going beyond the product to address the user’s task. OmniMark is a programming language for content processing, including SGML and XML. Through conferences, documentation, and particularly the developer mailing list, the company addressed all sorts of questions and issues about markup design and content processing that had nothing directly to do with the features of OmniMark. For a contemporary example, look at SynchroSoft, the makers of the oXygen XML editor, who do the same thing on their mailing list and forums.

In his book UnMarketing, Scott Stratten argues that the way you market yourself on the Internet today is to build a reputation as an expert in a particular domain. Become the person that people look to for information and answers on a particular subject, and sales of products and services will follow. This goes beyond content marketing — it is expertise marketing. This is where technical communication is going, I think, or at least the direction it should go — becoming an expertise marketing business asset.

This is not, then, a different way of writing the same old set of manuals. Tech pubs planning is no longer about figuring out how many feature descriptions have to be changed for version 3.2. It is about figuring out when and how to create content that enhances the reputation of the company as a source of expertise in its field, and supporting the users in their experience, to the full extent that doing so increases revenues and enhances shareholder value.



15 thoughts on “Are Docs a Responsibility or a Business Asset?

  1. pamela clark


    Thanks for another excellent article. I agree with your conclusion: “Tech pubs planning is no longer about figuring out how many feature descriptions have to be changed for version 3.2. It is about figuring out when and how to create content that enhances the reputation of the company as a source of expertise in its field, and supporting the users in their experience”

    During one of my job interviews this past summer, the director of engineering told me they wanted to create a “frictionless” sales model- he saw the product documentation as a huge part of this model. It was a very innovative vision of what documentation could mean for the company. I have seldom encountered anything at all like it in other software companies.

    Most places I have interviewed and/or worked in the last 10 years view docs in the “responsibility, feature-based model” that you describe. Perhaps this is one reason that “web content” with attendant blogs, articles, examples, forums and so on have become more prevalent, but don’t seem to be handled by tech pubs in most cases that I have seen.

    In many companies this “web content” is produced by an entirely different team than tech pubs – and includes engineers or draws from the expertise of the engineering staff. I’ve often wondered why there is not more collaboration and coordination in the production of these two kinds of “content”. For the most technical products out there (think tools and middleware, for example), this could definitely result in a permanent schism where writers principally produce reference content and others do the task-oriented, practical content demanded by today’s users. It may be a matter of expertise or it may be because the role of tech pubs has not broken out of the old paradigm.

    1. Neal

      “It may be a matter of expertise or it may be because the role of tech pubs has not broken out of the old paradigm.”

      I’d say it’s both, and also how other groups view the documentation team. In my experience, Marketing wants the subject matter experts to talk about the cool new feature, so they grab a product manager or an engineer. The tech writer possesses second-hand information, so why go to them?

      And documentation (user guides, release notes, etc.) are often seen as very formal, and not like a more informal blog or forum post. I think that tech pubs groups need to do a better job of positioning themselves (ourselves) as SMEs, willing and able to write about the product in less formal arenas in a less structured style.

      1. Mark Baker Post author

        Neal, thanks for the comment. It definitely seems to me that to play in this new space, you have to be the SME. The old model of interview the engineer, draft, review, approve, format, publish just takes way too long for this new environment.

    2. Mark Baker Post author

      Hi Pamela,

      Thanks for the comment. It is a good question why tech pubs are not being included in new content initiatives in many companies. I suspect it is in part a matter of the rest of the organization seeing Tech Pubs more as publishing people than as content people. (If you want respect, get out of publishing 🙂 ).

      I suspect also that if tech pubs managers were ever approached about other content initiatives, many would refuse out of hand on the grounds that they were too short staffed to meet their documentation commitments to the next release. (This may be shortsightedness on their part, but it may also be defensiveness — where does a traditional tech pubs manager fit in the new content space? Of course, that which will not bend eventually gets broken.)

      Add to that that many tech writers can be quite snobbish about the web and about anything to do with user generated content. It does seem, somethimes, that tech pubs is doing its level best to make sure it misses the boat.

      1. Neal

        “Add to that that many tech writers can be quite snobbish about the web and about anything to do with user generated content.”

        Snobbish and territorial. I should know, because I’m dealing with those feelings right now!

        I’ve been trained to deliver the highest-quality content possible. That’s what I’ve been doing for years, and I’ve been studying information architecture, content strategy, web design, etc. And now you want me to let the great unwashed (or at least untrained) write the documentation?

        These are scary times. Even for me, and I’m more than happy to get away from the old “research/write/publish a static PDF” model.

        1. Mark Baker Post author

          Isn’t odd how “quality” has become an excuse for not giving the customer what they want? The problem, I think, is that most of the things we were taught to regard as quality were actually shibboleths — in other words, trust mechanisms.

          Real quality, of course, is that which the customer values, neither more nor less. What the customer wants, what they have always wanted, is trustworthy help. What has changed is how they determine who to trust. They have new shibboleths now.

          Classically, literary professionalism and publishing craftsmanship were the hallmarks of trustworthy information. Now trust is much more social and personal.

          Perfect grammar and flawless typography no longer convey a compelling sense of technical reliability (perhaps because so many manuals have been written for so long by people who were completely out of their technical depth).

          People now prefer to trust those who show real technical grasp, and those who are clearly trusted by others, even if their prose is patois and their typography is wholly unconsidered. The fact is that it is the unwashed and the unlettered who increasingly deliver what quality has always meant: trustworthy help.

          It is not our job to get in the way of this. Indeed, those who try to dictate who others should trust are the ones who are least trusted of all.

          1. Neal

            Thanks for indulging me in this discussion, Mark.

            And although I would love to provide my users with the cleanest, most correct language in the documentation, I have to look at my own behavior. As a user, when I’m looking for an answer to a question I’ll often rely on a combination of product help, forums, and blog posts.

            No user has ever complimented me on my flawless sentence structure or the glory of my bullet lists. When I do receive a compliment, it’s almost always “I found what I was looking for, and I found it quickly.”

            As a user, that’s exactly what I want, too.

            A PM recently asked me why the documentation doesn’t have a topic for every page of the UI, describing every UI element in the product. Who would read that? (And when would I find the time to write more worthwhile topics?)

  2. Jonatan Lundin

    Hi Mark
    I’m glad that this discussion can continue, because it is of great importance. But you have misunderstood my slightly. I do NOT mean, by product centric tasks that technical communicators must document product features in a contextual vacuum, meaning not considering the business benefits it can bring and how the product can contribute to customer success. On the contrary. I’m actually meaning the opposite, which means that I agree to what you are saying in this blog post about technical documentation becoming a business asset. But I still argue that technical communicators shall not focus on dictating organization centric tasks. The misunderstanding maybe comes from our different interpretation of organization centric tasks. Let me explain how I mean.

    An organization has business goals. The business goal is to increase revenue, market shares, customer satisfaction and decrease cost etc. The business goals are reached by setting up various organizational goals, such as sell more products or services, develop more usable and qualitative products, constantly focus on optimizing, automating, enhancing processes etc. An organization has employees, each employee having one or several roles. Each role has a responsibility to contribute to the organization goal, and in turn to the business goals. Each employee executes the responsibility by performing various tasks in their daily work life. The organization themselves defines the responsibilities and the task each employee must do (the user manual shall not define how a user organization must be built up). These tasks are what I call the organization centric tasks. It can be concluded that several (maybe competing) organizations in the same business domain, may have in general the same business and organization goals, but differ in how the business and organization goals are reached, meaning how the organization is set up in terms of roles, responsibilities and tasks.

    Let’s look at my definition of product centric tasks. First of all, a product is purchased and used by an organization because they believe that the product can help them on their journey to reach their business and organization goals. A product is designed for a purpose, and that is to solve what I call the user primary goals. The primary goals can (and must!) then be mapped to the business and organization goals. I argue that user documentation must tell what primary goal(s) a product can solve, meaning to connect the product to a business context. Thus, user documentation must include information to help the user evaluate if the product can or cannot solve their business/organization goals. What can the product do and how is it done? To make the product solve the primary goals, the user must reach for a set of secondary goals; to install, configure, verify, use, evaluate etc. To reach the secondary goals, the user must perform a set of tasks. The tasks to reach the secondary goals, is what must be included in user documentation. And, these tasks are what I call product centric tasks. Product centric tasks may very well include descriptions on how a product interacts with other type of equipment and how to connect to other equipment and what “supporting products” are needed.

    I still argue that technical communicators must not focus on organization centric tasks. This is what I mean. The term “user documentation”, shall be interpreted as the “started set” that is shipped with the product, not any discussions or advices channeled through for example a public forum etc. User documentation must instruct the user on how to use the product to reach the secondary goals and in turn the primary goals. User documentation must not be built to require that the user organization must have a certain set up of roles and dictate what tasks the roles must do in their daily life. I argue that each organization is clever enough to figure out how a certain role responsibility must be changed when a new product is implemented, given that they understand the tasks presented in user documentation. Consider role based manuals for a product: an operator’s manual, a maintenance engineer manual and a system configurator guide. What is this telling the user organization? “To use this product your organization must have an operator role, doing tasks X, Y and Z, a maintenance engineer role doing tasks A, B and C and a system configurator role doing tasks 1, 2 and 3. If your organization does not have such roles, then implement them or you will fail in using the product.”

    The product centric task approach means that tasks in a user manual, must not be mixed up with organizational centric tasks. For example (as we discussed on Tom’s blog): You don’t need to state in the user manual that, to use the product correctly, the user must inform the boss when a CO2 alarm sets off. Simply, because that is not from a manufacturer point of view a strict prerequisite to make the product deliver a result that solves a primary goal. It is up to the organization to decide whether the boss shall be informed or not. If you must include the organization centric tasks in your documentation, which ones do you include, since each organization has their own way of doing things. As we also concluded, a manufacturer may very well discuss and give an advice on public forums that it is best practice in a certain domain to inform the boss.

    My concern is that many technical communicators are focusing too much on organization centric tasks, thereby missing an important aspect. Technical communicators (including myself some years ago) focus on describing and analyzing user organizations, where user groups and target audience are identified to try to build a universal set up of roles/groups and predict their tasks. But why is a user doing a task? Users don’t do tasks because it is fun to do them. As a result, user manuals are often introducing a lot of tasks, but technical communicators often miss to provide the “meaningful glue” that helps the user understand what the purpose and goals of doing a set of tasks are. The missing aspect is what primary goals the product is designed to solve. That’s why I developed SeSAM. SeSAM is a methodology that helps technical communicators focus on how their product can help users becoming successful, thereby making documentation a business asset.

    But, what I’m also saying is that organization centric tasks must be considered when a product is designed, meaning how to design the user interface etc. A product must be designed so that it can be implemented by the user organization without greatly modifying how things are done in the organization (user competence etc). If a product requires a great organizational change, nobody will buy the product. If a product is designed to meet its target audience, the user will be able to easily understand the product centric tasks will presented in user documentation.

    I’m also saying that a manufacturer can very well discuss and help a user, regarding questions on problems or how to change the organizational set up, on public forums, mailing lists etc. But to require a certain organizational set up in user documentation is not what I would like to see happen.

    If you do not agree that technical communicators, when documenting a product, must first start from the primary/business/organization goals the product can solve, from there derive the secondary goals and model the tasks the user must do to reach the secondary goals; how should the tasks to include in a manual be identified? Where do you start and go next?

    1. Mark Baker

      Hi Jonatan,

      Thanks for the comment, and for clarifying your meaning. I understand your position much better now, though I actually disagree with it more now than I did before. 🙂

      You say:

      A product must be designed so that it can be implemented by the user organization without greatly modifying how things are done in the organization (user competence etc). If a product requires a great organizational change, nobody will buy the product.

      I disagree completely. In fact, the history of the high tech industry over the last 50 years is all about changing how things are done in an organization. From Wikis to Blackberries to SharePoint to Agile to Kanban to CRM, and just about anywhere you look, people are selling business process change, and following up with tools that implement the process.

      In the Pubs world, Desktop Publishing completely changed how content creation was done in an organization, and you had to sell the model — the author as sole craftsman doing everything on the desktop — before you could sell the hardware and software. I actually worked for a desktop publishing company in the 90s, back when the model of work for most organizations what that you sent copy out to be typeset. A bunch of small companies sprang up that used desktop publishing tools to deliver typesetting services more cheaply than traditional typesetting companies. Of course, the vendor of laser printers and DTP software wanted a larger market for their products than a bunch of cut-rate typesetting companies, so they soon shifted their marketing attention from the print shows to the tech comm and marketing shows, peddling a radical change in how businesses should do publications. To sell those products into the business market they first had to persuade businesses to make a radical change in how they did publishing.

      We are now in another wave of change in publishing, which is again being led by people advocating a process change. Yes, there are vendors out there trying to sell the notion that you just buy their word add on and bingo, you will be doing structured writing. But any serious consultant or vendor in the space will tell you that this move is about changing how you work in fundamental ways, and that you need to be prepared to make the transition.

      And I think this is the story across the tech industry. The lead is organizational change, and if people buy the product without making the change, the result is often dissatisfaction and loss of productivity, which leads to bad word of mouth about the product, which leads to poor sales. Companies therefore have a great interest in making sure that their customers make the process changes that will make the product work for them. The docs can do a lot to help this, and they should.

      SeSAM is a methodology that helps technical communicators focus on how their product can help users becoming successful, thereby making documentation a business asset.

      This is, I’m afraid, the very idea that I was trying to argue against in this post: the idea that there is a set role that documentation must play, which can be defined in universal terms. The appeal of such a definition is that allows you to presume that if you fulfill the universal definition you must, ipso facto, be creating a business asset. But this is not necessarily true at all. The only definition of a business asset is that it drives revenue and builds shareholder value. We are in a period of profound business upheaval in which one business after another is discovering that things that were business assets yesterday are liabilities today. And businesses are not at all shy about hacking away any vestige of the past that cannot prove that it is pulling its weight today. This is the very worst time, it seems to me, to be building a box to put technical communications in. We need to innovate and experiment and break down the walls between departments and functions as never before. We need to reinvent ourselves for the future, not cement ourselves in the past.

      1. Jonatan Lundin

        Hi Mark,
        Thanks for sharing your perspective. It is always interesting to discuss matters with someone having a different view on things. That’s what makes life interesting. This discussion has provoked me to write a blog post. See

        You said: I disagree completely. In fact, the history of the high tech industry over the last 50 years is all about changing how things are done in an organization.

        My statement wasn’t about whether a product is designed to introduce a paradigm shift or not. I agree that the objectives for many manufacturers are to develop products that introduce new processes. I was talking about the interface design and the effort and knowledge a user must put in to be able to use the product. Let’s say that a product really would change the way things are done. But the user interface and the tasks the user must do are so awkward and difficult that it would cost a lot to learn how to use it. Difficult and awkward in a sense where the design of the product interface and the tasks the user would need to carry out did not take the characteristics of the user group into account. The user may found out that there are no ROI and decides not to buy the product. A user may instead buy a competitor product that gives the very same process change, but the design of the user interface and the task the user needs to do are better aligned to the user capabilities.

        I’m not saying that documentation must be a business asset just because it follows a universal architecture. But, I do believe that there is a set role that documentation must play; to help users solve their problems, needs or requirements as fast, easy and securely as possible using the product. I see this role as a universal role. That is, any manufacturer wants happy and successful customers. In your view, what kind of role shall documentation play?

  3. Pingback: The Costly Myths about Documentation | Shoap Technical Services

  4. VS

    “I took over one user manual that told the user that if they did such and such an operation, the phone would emit a tone of so many megahertz for so many milliseconds.”

    Merlin’s beard!!!! How long ago was this? 🙂


    1. Mark Baker Post author

      I don’t think I want to admit how long ago that way. It might date me!

  5. Tom Johnson

    Mark, thanks for another illuminating blog post. I especially like what you say here:

    “Thus the objective of technical communication becomes not to fulfill a responsibility to thoroughly document an individual product, but to enhance the user experience of people who bought the product.”

    The shift from a responsibility to the product to a responsibility to the user seems like a worthwhile focus.

    However, here’s the situation I’m running into. What happens when the company wants users to do A, but users want to do B? All the budget is allocated for goal A, and not so much for goal B.

    To be more specific, in my case, users want tips, tricks, and other information about our organization’s flagship product. But the budget focuses on recruiting and integrating volunteers to help test, design, and develop other products.

    Do technical writers have a responsibility to the organization, or to the user?

    1. Mark Baker Post author

      Hi Tom. Thanks for the comment.

      I think that the tension between the reader’s aims and the writer’s aims is a constant in tech comm (Writer vs. Reader is actually a category on this blog). Sometimes this is legitimate (buyer and seller do have different aims at the best of times) and sometimes not. In the end though, as an employee, your responsibility is to the person who signs you check.

      Of course, to say that your responsibility is to the person who signs the check is not to say that you should always do what they tell you without question. The point of hiring a professional is that they know more about their field than you do, so if you don’t listen to their input, you are probably overpaying them and under-employing them.

      The writer’s responsibility as a professional is to advocate to the company that better serving the customer will create more shareholder value for the company. I think that where many writers get into trouble is that they lose sight of shareholder value and attempt to serve the user in a way that is abstracted from the market.

      The truth of the matter is that the market is the guide to whether you are creating customer value or not. Thus creating customer value and creating shareholder value are not at odds with one another (baring deliberate manipulation of share prices, of course).

      Of course, this is not to say that the current corporate strategy is actually creating customer value. It may be destroying both customer value and shareholder value, in which case you have a responsibility, within your sphere of professional competence, to point out the discrepancy. If told to shut up and do as you are told, however, your responsibility is either to do it, or quit.


Leave a Reply to Mark Baker Cancel reply