Training Bulletin Issue 23

How to lose $35 million in three months

A company once lost $35 million 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 organise 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 enquiry 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. These are some of the areas covered in our two-day workshop on Designing and Writing Technical Documents.

Call 01235 60 30 22 or email to find out more, or check the full technical documents course outline.

Happy ending

If you’re interested in more details about Coleco and the Adam computer, you can read about it here

You may be pleased to know there’s a happy ending: Coleco went on to recoup their fortunes with Cabbage Patch Dolls.

Editor recommends

Technical Writing 101 — A Real-World Guide to Planning and Writing Technical Documentation – Alan S. Pringle and Sarah S. O’Keefe

This is a straight no-nonsense and practical guide to planning, researching, writing, indexing and polishing technical documents. It includes advice on formatting and using graphics, and even on how to become a technical author!

Public course schedule

Follow this link for the dates of our public courses.

The price is £495 + VAT per person for a one-day course and £850 + VAT for a two-day course. Half day courses are £295 + VAT per person.

We also offer private courses at your premises. Please call 01235 60 30 22 for details.

How to book

To book, call Abi on 01235 60 30 22 ext 20 or use the booking form.

Kind Regards
The Plain Words Training Team