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.