Trust is Essential to Creating Great Docs

By | 2011/10/31

My good friend Pamela Clark asks me to comment on

what product development organizations, processes, and structures best support great user-oriented documentation

I’ve commented over on Tom Johnson’s blog that tech pubs organizations tend to make a slow migration through the corporate landscape, and that I believe that the best home for pubs is in the development organization. But I also believe that tech pubs success is all about relationships, and there is more to that than simply the reporting relationship. In the end, if you want to create the conditions to do great work in tech pubs, you have to be valued.

For a tech pubs team, being valued in an organization is not always easy. I think there are some basic conditions that must be satisfied for tech pubs to be valued by other parts of the organization.

Docs have to be a differentiator

First, documentation has to be a differentiator for the product in the marketplace. In other words, the docs must make a difference in how many people buy your product (market share) or how much they are willing to pay for it (margin).

This is not always the case. The Tilley hat company actually advertises that their hats come with an owner’s manual. Tilley is marketing a premium hat, and they clearly think the owner’s manual is a differentiator for them. But few other hat companies are likely to be able to increase their margins or market share by providing an owner’s manual for a hat. Docs simply don’t make a difference to every product.

Even where docs can make a difference, people don’t generally see the docs until after they have bought the product. In this case, docs don’t contribute to the immediate buying decision. Where they can make a difference is in the product’s reputation. Good docs can improve customer’s productivity and general satisfaction with the product, thus leading them to buy more, or to recommend the product to others.

However, docs do sometimes come into play before the purchase is made. In the case of complex business to business sales, documentation can be a factor in a successful product evaluation. Sales people will sometimes use documentation as part of their sales collateral. Even for simple consumer products, documentation can work as a marketing vehicle.

One thing is certain, though: if the docs do not have a significant impact on the product’s performance in the marketplace, it will be impossible to consistently get the resources you need to do good work in pubs.

Company must know that docs are a differentiator

Even if the docs are a differentiator in the marketplace, the company has to know that they are before they will value the tech pubs function. But the company often doesn’t know. The impact of documentation does not always show up in corporate data, and it can be difficult to separate the impact of the docs from that of the product itself.

The fact is that many companies produce documentation simply because it is conventional to do so in their industry. It is a check-box item, and they don’t take much trouble to determine its impact beyond whether the box gets checked or not. (Many tech pubs managers will have had the experience of sitting in a project meeting being asked if the documentation will be ready on time, and realizing that the only answers anybody cares about are “yes” and “no”. Any qualification of the answer based on quality or completeness is ignored or transmuted into a simple “yes” or “no”. And “no” is the wrong answer.)

Compounding the problem for pubs is that if the corporation does not know, the chances are pubs does not know either. They don’t know if the docs they are producing are a differentiator, or whether they are helping or hurting the bottom line.

Company needs to trust the pubs team

As long as pubs are just something that you have to have, but which don’t make a significant difference to the bottom line, a pubs group can plod along in obscurity. They won’t consistently get the resources they need to do good work, and they will be the first place people look when cuts have to be made, but apart from that, people will generally let them do their thing without interference.

However, if and when the company comes to see tech pubs as making a significant difference to the bottom line, pubs will find itself under scrutiny. The question then becomes, does the company trust the pubs team to make the decisions and create the products that are going to improve company performance?

That answer will probably depend on whether the company has discovered that the docs are having a positive or negative impact on performance. If it turns out to be negative, tech pubs’ request for more resources to address the problem may fall on deaf ears. After all, pubs is the team responsible for the the current docs that are hurting the company. Why throw good money after bad?

This may be unjust — the pubs group may be capable but chronically under-resourced, it may be in the middle of a major improvement project — but this probably won’t matter. The rest of the company does not understand tech pubs or how it functions, and so it will be hard to establish trust when the salient business fact is that the documentation is pulling down product performance in the marketplace.

Pubs needs to embrace business values

How did we get ourselves in this mess? The sad fact is that tech writers tend to ignore the business impact of what they do. This leaves the pubs function unable to justify its resource requests and unable to defend itself when its utility and competence is questioned.

Yes, it is hard to get the stats. It is hard to gauge the impact of documentation. But that does not excuse us from thinking of our function in business terms. And let’s face it: we don’t. We think of our function in craft terms. We think about readability, typography, aesthetics, usability, grammatical correctness, layout, and design. In short, we think about quality rather than value.

Quality is important, of course. But a product can display a high degree of craftsmanship and still not be of value to anyone. In short, if you make the wrong product, making it well does not change the fact that it is the wrong product.

What’s more, the right product made badly has more value than the wrong product made well. If we are not producing the information that people want, it doesn’t matter if it is of the highest quality in terms of readability, typography, aesthetics, usability, grammatical correctness, layout, and design.

As Tom Johnson notes in Why Rubrics Fail as a Means of Measuring Documentation Quality, we tend to measure ourselves against a set of craft rubrics when we should be measuring ourselves in terms of the outputs we produce. But the rubrics are seductive. They are much easire to measure ourselves against, and much easier to satisfy on a regular basis, than any measure of buisness impact of our documentation. The rubrics keep us from thinking in business terms.

But if we really want to make a case for the resources we need to do good work, then we have to think in business terms. And the question — the business question — is not how we measure up to the craft rubrics, nor is it even what users want; the question is, what will users pay for? What can we do with documentation that will increase market share, increase margins, or decrease costs? Until we start thinking about every decision we make and every document we write in those stark terms, we will not be thinking of pubs as a business function, and we won’t have the answers we need when people challenge our usefulness.

Thinking in business terms can’t be something that doc managers do for a week each year at budget time. It has to be something that every member of the pubs organization does all year long. Once we do this, though, I think that great things will begin to happen for us. Data or no data, if we talk and think and act in terms of these basic business values, we will be talking and thinking and acting in terms that the rest of the organization understands and respects.  With that comes trust. With trust comes the ability to secure the resources we need to do a good job.

6 thoughts on “Trust is Essential to Creating Great Docs

  1. pamela clark

    Excellent post, Mark. I have been at my new gig for almost 8 weeks now. As you know, I work at a mid-stage start up, still privately held, in Silicon Valley. The company is positioning itself to go to the next level with new exec team, new marketing message, and so on.

    I can definitely say that the docs team here is trusted by the product development team, the field engineers, and the professional services team. This has been evident from day one. I also think that the docs manager thinks in business terms. Whether the docs are a “differentiator” for the company and the extent to which the company as a “whole” knows this and values it, are harder to discern, at least for me.

    At our recent technical summit, which involved all of engineering (including docs) and the entire field organization, the docs manager was asked about the “future” of docs. His answer was a bit vague, but did include a mention of wanting to embrace “design patterns” for building apps on top of our product, which seems to make a lot of sense. However, a somewhat puzzling comment was his assertion that even when readers of the docs tell him “the docs are good”, he doesn’t believe them. I found this fascinating, but don’t understand it yet.

    Another aspect to consider is the relationship between documentation written by tech pubs, which is largely reference-oriented to date, and content found on the online “developer community”, which is mostly written by developers. And, if all documentation is online and public (which ours is), then how to measure what “customers are willing to pay for”. This is all food for thought, as you say.

    More thoughts on what constitutes being “differentiator”? I’m still thinking about this and how to measure it. Thanks for writing on this.

    1. Mark Baker Post author

      Hi Pamela,

      Thanks for the comment. I think for developer tools of any sort, design patterns are a really key, as you and I have discussed in another context. I think this is an area where documentation can be a very real and substantial differentiator. I certainly think that that was the case for a former employer of mine, OmniMark Technologies. I think that their whole business, including their main product, the OmniMark language, was based on the design patterns they developed for SGML/XML processing. People bought the product because they saw the power of the design patterns.

      What sells a tool, more than anything else, is the kind of solutions it allows you to build. Design patterns are at the heart of that and if the docs can show the design patterns clearly, I think that can really help drive sales and margins.

      I think it’s great that your manager is not satisfied when the users say the docs are good. If necessity is the mother of invention, dissatisfaction is the mother of improvement.

  2. Larry Kunz

    Well said, Mark. If the pubs department doesn’t think in business terms, nobody else will do it for us. We talk a lot among ourselves about the

    value of documentation, and we tend to assume that its value is self-evident. In reality we need to produce the evidence, and it needs to be expressed in terms of return on investment.

  3. pamela clark

    @ Larry – can you give an example of producing the evidence expressed in terms of ROI?

    1. Larry Kunz

      Pamela – As an example of what I’m talking about, my company gave a presentation on how an organization can use DITA to produce more content with less investment. I’m not suggesting that it’s all about DITA: you could make a similar case for any one of your department’s processes and workflows. The point is, this presentation relies on common business metrics rather than resorting to the comfortable rubrics that Mark referred to.

      Here’s a link to the presentation.

      1. Mark Baker Post author

        HI Larry,

        Indeed, cost reduction is an important business metric, and it is naturally going to be a big part of how a vendor positions their products and services in the technical communication space.

        However, I think it can be dangerous for a pubs department to make a case in terms of cost reduction alone. There are two problems with a cost reduction argument. First, cost reduction in your own function does nothing to prove that you add value. For that you need to show how you impact market share and margins. There is no prize for making something of no value cheaper.

        Second, by making the cost reduction argument, you draw attention to how much it costs the organization to support the tech pubs function. Once you put the issue in play, you may find that other people will have different ideas about how to reduce tech pubs costs.

        I would always encourage groups to lead with an increased value argument rather than straight cost reduction.


Leave a Reply