A company once lost $35million in one financial quarter, due to the failure of one product. The company was Coleco; the product was the Adam computer, and the blame was-at least partly-put down to ‘manuals which did not offer the first-time user adequate assistance.’
Good technical documentation is as important as a good product, and bad technical documents can kill a good product. Documentation shouldn’t be left as an afterthought, or fobbed off onto someone with minimal knowledge of the product or service. In fact, it can be nearly as bad to have it written by someone with deep and expert knowledge of the product, because an expert can find it hard to appreciate the position and requirements of new users.
So how can you make sure your technical documents are on target with the users’ requirements? A good start is by addressing Plain Words’ 6 W’s of technical documentation – in fact these pointers apply to writing any kind of document:
**1. Why are you producing this document?**
To inform? To instruct? To represent your company and your service to your customer?
** 2. What does your document need to include?*
What information must it present, in what order, and what structure will convey it most clearly? What sort of image do you want all your literature to reinforce?
** 3. Where are you going to find the information?
How can you extract it from people who don’t have time to talk to you? How can you best verify and organize it?
** 4. Who is going to read it?**
How much do they already know? What don’t they know? What do they need to know?
** 5. How (we never said they’d all start with ‘w’) will your document be used?**
On-line or printed? This tells you if you can embed links or use print-related conventions like ‘see below’. Will it be read in a leisurely spirit of inquiry or in a frantic search for the answer to a crisis?
** 6. When is your document due, and what needs to happen before you can deliver?**
What are the critical milestones and how do you stay on track? Is there time to revise as the product goes through development? Have you identified reviewers and built in time to incorporate their comments?
You should spend at least as much effort on planning your user documents as you do on writing them. These six questions will help you focus and plan so that the end result contains the right kind of information for your user.
**Happy ending**
If you’re interested in more details about Coleco and the Adam computer, you can read about it here:
From Time Magazine http://www.time.com/time/magazine/article/0,9171,951198,00.html?promoid=googlep You may be pleased to know there’s a happy ending: Coleco went on to recoup their fortunes with Cabbage Patch Dolls.
Designing and Writing Technical Documents
These are some of the areas covered in our two-day workshop on Designing and Writing Technical Documents. Call 01635 202013 or email training@plainwords.co.uk to find out more, or check the full course outline at http://www.plainwords.co.uk/co_technical_documents.html
Telephone: +44 (0)1635 202013
0 Responses
Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.