Monday, January 31, 2005

Writing User Guides

I'm soon to attempt version three of our intranet CMS user guide - we have a good handle on what our users want and need to know, as they are pretty good at providing feedback, and I tend to act as the coalface for this. My issue is more in supporting the various different modes of learning that our users have (they range from the technically not knowledgeable to the technically very knowledgeable indeed!) and making sure that they move from passive reading to active learning.

With this in mind, I've been looking at various types of software training books to try to get a handle on as many different learning types as possible. So I've come up with the following ideas:
  • use common-sense names as well as the technical names for all aspects of the system in the section title even if this makes it quite lengthy;
  • use plenty of "What you need to know" call-outs - make these hands on demonstrations of key points of the system;
  • use as many illustrations as possible - not just of the system, but some pictures/photos to make neophytes feel at ease (e.g. photo of a user using the system);
  • keep the illustrations with the text they illustrate (not just "close to");
  • repeat information over and over in as many ways as possible - for instance the "big picture" view, the "step-by-step" approach, the "case study" etc.;
  • Have illustrative step-by-step instructions on the page, but back these up with animations of a user achieving these (ie. instructions backed up with a demo);
  • run short end-of-section exercises to test the reader's knowledge;

Does anyone have any foolproof tips to add to this list? I'd really appreciate any input. As an NB: we do - of course - test the guide with users before releasing it, but are restricted to no more than three users, and not necessarily of all the types of user we would like to test against.

No comments: