product guide documentation how to instruction manual

[Guest Blog] Love the product, shame about the documentation

Author: Terry Freedman

Terry freedman is a freelance ed tech writer and consultant. He blogs at ICT & Computing in Education, and tweets as @terryfreedman.


What’s the problem?

Once a school has purchased your ed tech product or service, what then? In my experience, a lot of great products are let down by terrible documentation. That doesn’t necessarily mean it’s been written badly. It may be good, but just not useful. It may be too detailed, lacking in detail, or it may fail to address one simple question: what does the user actually want to achieve?

Let’s take an example. Suppose you sell a digital camera specifically designed for school use. It’s robust, brightly coloured, easy to see when it needs charging up, and so on. Although it has a few simple controls, you can do a lot more with it if you know where to look. Fine. The temptation is to write a manual that covers every single function, listed in alphabetical order. The manual, weighing in at 198 pages, is supplied in a pdf format, available online.

The box contains a “quick-start” guide which tells the user to start taking pictures straight away by pressing the big red shutter button.

What’s the solution?

Neither of these guides really address what the busy teacher, with a classful of kids probably wants to do, which would be:

  • Take photos.
  • Pass the camera around so that the kids can take photos.
  • Get the photos out of the camera and upload them to somewhere central, where they can be viewed by the whole class and possibly others too, like parents.
  • Charge the camera after use.
  • Make room for more photos when the SD card becomes full.

None of that is rocket science, but each step could cause less confident teachers to worry: will the camera break if too many kids handle it? What if someone drops it or spills orange juice on it? What if I can’t get the SD card out? How do I put it back in? What if there are photos that we want to delete?

The differences between the all-encompassing PDF manual and the sort of manual that would address such points are:

  • The user-centred guide is available: the information could go on a card or an A5 sheet of paper. No hunting for, and then downloading and printing PDFs. No hunting through the index or table of contents trying to second guess what the writer may have called the thing you’re looking for.
  • It’s pragmatic. It gets the teacher (and therefore her class) going right away. 
  • It covers the subject from the point of view of the user, not the technical author who wrote that huge PDF.

How to write the manual

Thinking of the user, consider these suggestions:

  • Write different manuals for different people, or people at different levels of expertise. For example, an additional guide, to take the camera example, might be called “How to get more creative with your camera”. That would suit someone who has gone beyond “point and shoot”.
  • Write in lists. You’re not trying to win the Costa short story prize. Use numbered lists where the order is essential; use bullet points where it isn’t.
  • Include screenshots: a picture paints a thousand words and all that.
  • If possible, get a teacher to write the manual (and pay them).
  • If possible, ask other teachers, and pupils, to test the manual or guide before you have thousands of them printed.

Concluding remarks

Don’t let your product be let down by poor documentation, or good documentation that has not been thought through. A printer I bought a few years ago had very precise instructions on how to open the packaging without damaging the contents. Great idea, marred only by the fact that you had to open the packaging to find it!

A well-written manual, perhaps with some humour, could even become a talking point in itself.

Please follow and like us:
Follow by Email
Terry Freedman

Terry Freedman is an independent educational ICT consultant and writer, having had a long career in Education, including teaching, advising schools and inspecting. He publishes the ICT and Computing in Education website at, and the Digital Education newsletter at You can follow Terry on Twitter @terryfreedman.

Click Here to Leave a Comment Below

Leave a Reply: