Monday, 26 May 2008

Can better technical documentation give your business a competitive advantage?

Many businesses regard the need to produce user documentation for their products as an unfortunate and expensive necessity, and they are therefore ready to classify their tech docs department as a "cost centre", rather than a "revenue centre". When times get tough, workers in "cost centres" are the first to feel the squeeze.

As someone who as spent the last 15 years of my professional career producing user documentation I am bound to see this attitude as wrong. Good technical documentation which focuses on user tasks helps people get their work done using the products you sell. People who are happy using the products you sell are more likely to renew their support license next year, or to upgrade to your next release, or to specify your products for their next expansion. They are less likely to clog up your customer support lines with trivial questions about your products. These are definite financial benefits to your business, but they are difficult to quantify.

Luckily there is a contrasting attitude that is beginning to gain popularity. In this approach, all types of information within a business organisation are regarded as business assets, that need to addressed, managed, and exploited. A recent blog on The Content Wrangler web site, written by Jake Sorofman of JustSystems takes this idea one step further. In Thinking Outside the (Tech Docs) Box: Structured Authoring as Competitive Advantage Sorofman emphasises the advantages of adopting an information management policy based on a system of structured authoring. He places technical documents - the user guides and help systems used regularly by customers - at the centre of the corporation-customer relationship, and calls such documents "value generators" as they help build trust and confidence. Structured authoring, which allows content re-use to create multiple and flexible (and in some cases, on demand) information products from the same sources, means that writers can become more efficient. One of the most interesting systems for structured authoring is the Darwin Information Typing Architecture or DITA, which is an XML specialisation managed by OASIS.

Sorofman makes a convincing case for technical writers and their work to be recognised for their significant role not only in providing user documentation but in building the customer relationship, and of course, I think he's quite right.

I hope to be offering more comments on DITA in this blog in the next few weeks.


Unknown said...

Good article, thanks.

Unknown said...

I've recently decided to become a freelance technical writer, and your article caught my eye. To assist me with some of the mundane IT system documentation, I'm using documentation generators (e.g. Adivo's TechWriter for Databases
I'm very happy with the tool, and I think it's giving me a technical advantage over others because I can generate/update doc quickly and add my own annotations and additional content easily. But I wonder what your opinion is of such documentation generators and if you think they help or hinder the process of making better documentation??
Thanks for any advice.

David Farbey said...

Hello Anne,
Thanks for your question.
Tools like the one you describe are useful if documenting databases are the core of what you need to produce, and they serve the needs of your audience. They may have a secondary benefit in helping you understand the inner workings of the programme you are working on.
If you are producing documentation for non-technical users, you need to concentrate on their tasks, from their point of view - which is often far removed from the way things look to the database developer.