WHY YOU NEED A QUALITY AUTHOR
by Mike Unwalla, MISTC

"Users don't want documentation, they want answers". That's true, but how do you give them the answers? Through documentation. (Of course, there are other options such as helpdesks and training courses).

Documentation costs money, but not providing it will cost you a lot more money in the long run. This article looks at some of the issues involved, namely costs, the relative merits of online and paper documentation, the properties of an ideal author/writer, and pre-requisites to producing effective documentation.

For the purposes of this article, let's define documentation as supplementary material that is provided with a software product with the aim of aiding users to perform business tasks. This covers a huge range of options such as user guides, reference manuals, WinHelp, compiled web help, release notes and FAQs on a web site. This definition specifically excludes Wizards, since they are in inherent part of the software, and do not stand alone.

Costs and Benefits

Although providing documentation costs money up front, if you don't provide it, you are likely to incur greater costs later. Without a detailed analysis, it's impossible to quantify, but according to Saul Candib, "Microsoft estimates the total cost of a single call answered by a help desk technician to be more than $20 per call - regardless of whether the technician can provide an answer" and "Microsoft ITG estimates that a few common topics account for 80 percent of the calls they receive" (Saving Time, Money, and Expertise with a Self-help Support System, Saul Candib. Microsoft TechNet, May 1997, Volume 5, Issue 5).

So, if you have a helpdesk, usable documentation that provides answers is likely to reduce costs considerably. If you do not have a helpdesk, consider what it costs if software developers provide technical support.

Additionally, there are all the indirect costs such as lost custom through bad referrals to third parties, customers choosing competitors when it is time to upgrade or not purchasing other products from your company.

Online versus Paper

Obviously, you want to reduce your production costs, and an initially promising way of doing this is to produce only online documentation. There are other advantages too, for example, it's always available and it's guaranteed to be the correct version. From a user's perspective, it allows easy access to cross-references using hyperlinks and searching on keywords is a boon.

However, not all material is suitable for online presentation. For example, any information that is needed before software is installed should be on paper! Material that requires extensive reading is not a good candidate for online documentation. Reading from a screen is more tiring on the eyes than reading from paper, and studies have shown reading from the screen is about 30% slower than reading paper.

Some companies provide user guides and reference manuals in electronic form; users can print these if they want to. In some cases this may be appropriate. However, it can be seen as dumping a production problem onto the user - is that the image you want to project?

Using SMEs

Who do you use to produce the documentation? A common misconception is that the ideal technical author should be an SME (subject matter expert). Now in some cases this can be an advantage, for example, if members of the target audience are also SMEs.

One danger of using SMEs to write documentation is that because they are so familiar with the terminology (jargon), assumptions and shortcuts in the subject area, they forget what it is like to be new to the subject. They make logical jumps that are not understood by non-experts. They don't state things that are "obvious"-forgetting that the intended audience does not perceive the "obvious". Even SMEs who are also experienced authors have to remind themselves of this.

Conversely, there is a major advantage in using authors who are not SMEs when the intended readers are not experts. These authors are likely to make the same mistakes and assumptions as the audience, and they are likely to ask the same "dumb, stupid questions" that the intended audience will ask. Capture these mistakes, assumptions and questions, and you are well on your way to improving the quality of documentation and reducing calls to your helpdesk.

This is not to say that authors should not have a general competence in the subject area. For example, if you have a relational database product, it's useful for the author to know at least the rudiments of SQL.

Getting the Facts

OK. You've decided you need documentation and you've got your author(s). How does an author start to produce effective documentation? At the start of this article I quoted a well-known phrase. Re-stated this means that the purpose of documentation is to aid users to overcome problems, understand tasks, make decisions and perform tasks more efficiently.

It's no use producing documentation that is well-written, attractive and easy to use if it doesn't answer the questions that users ask. Therefore, before starting to write, the author should know about the intended audience (there may be a mix such as novices, infrequent users and experts), the business tasks they want to perform (aided by the software), and the environments in which they work. With the business needs in mind, the author can then design and produce an appropriate mix of documentation.

Summary

There's one guarantee: you won't be able to please all the users all the time. However, with a careful evaluation of the typical users, their working environments and the tasks they need to perform, it's possible to create high-quality documentation that fulfils most users' needs. The bottom line is that providing good documentation aids your customers to perform their business tasks effectively. This in turn reduces your support costs and increases your reputation.

 

Download Article (Microsoft Word format)

If you would like any more information on providing quality documentation please contact
Mike Unwalla, MISTC
TechScribe
24 Spooner Road, Sheffield S10 5BN
E-mail: mike@techscribe.co.uk
Tel: 0114 266 6933

Affiliated to Independent Quality Authors on http://www.qualityauthors.co.uk

Article Disclaimer