Technical Writing: PRODUCTS SERVICES CLIENTS EXPERIENCE AuthorIT   HOME
 
Software User Guides  
Reports of the death of the user guide have been greatly exaggerated!

Despite the obvious benefits of online help there are many circumstances where some form of user guide is still desirable, or even essential. There are some applications, for example, that are just not suited to on-screen instructions because they interfere too much with access to the user interface. And then there are those markets in which users simply expect a user guide and will not take seriously any application that doesn’t have one.

Unfortunately, what they frequently get is a function-by-function description of the menu options with little or nothing in the way of guidance on how the application works, or on how to use it.

The software guides we write have the emphasis very firmly on enabling people to understand and use the application easily and effectively.

Although we can design infinite variations to suit individual requirements, many of the software user guides we produce fall into one of two general categories – those often referred to as ‘getting started’ guides, and full user reference guides.

Getting Started Guides
These are designed purely to provide an introduction to the software and to act as an accompaniment to the online help. Typically, they are only slim stapled or perfect-bound documents which, depending on the software, may include:
  • an overview of the application, outlining its main features and capabilities.
  • instructions for installing the software - but only up to the point where on-screen instructions take over.
  • a guide to the main functional modules or areas of the software.
  • a general guide to the principles of using the application – but no detailed procedures.
  • a brief guide to the online help and/or online documentation from which users are expected to obtain all detailed operating information.
These simple guides satisfy users’ requirements for a tangible document, without providing the sort of detailed information that is affected by changes to the application. All such detail resides in the online documentation or help system, where it can be updated quickly and without incurring reproduction costs.

User Reference Guides
Our comprehensive user guides are a different matter altogether. They are usually designed to cover every aspect of the application in detail, providing people with all the information they need to understand and use it to full effect.
  • We make sure that the structure properly reflects the way the application is intended to be used.
  • Where necessary, we provide detailed explanatory information to ensure that users understand the functions and concepts involved.
  • We use a language style and terminology that are appropriate to the nature of the application and its users.
  • We strive to make the guides as concise, relevant and easy to use as possible, but not at the cost of essential information, or by avoiding complex subject matter.
  • And above all, we provide accurate, tested, stepped instructions for performing specific, identifiable tasks.
Our user guides are all individually designed, and so vary greatly from one to another according to the requirements of the particular application. Normally, however, they start with an overview of the application which describes what the software is designed to do, outlines its main features and benefits, shows the overall arrangement of functions, and explains the general principles of using the application. In short, it’s designed to provide rapid familiarisation for new users of the software.

This is frequently followed a Getting Started section which guides the user, step-by-step, through any necessary configuration and set-up process, and through the basic essentials of operation. All normal operation is then covered in detail by task-related sections, each providing concise explanations for each logically-related group of tasks, together with stepped procedures for completing them. Where appropriate, we include screen captures, illustrations or diagrams, annotated as necessary.

Virtually all guides incorporate features such as a comprehensive index, and extensive cross-referencing between relevant sections and to the associated online help topics. Depending on the application, other elements, such as menu maps, glossaries and function indexes, may also be included.

Delivery options
Although we tend to think of user guides primarily as printed items, the distinction between hard-copy and electronic documents is actually getting a bit blurred these days. Using formats such as HTML and PDF (portable document format) we can prepare any of our guides for delivery either as finished printed documents or as electronic files which users can print locally or view on screen. You can supply the files in a variety of ways - on CD ROM or via your website, for example - giving users the option of a hard-copy guide without giving yourself the headaches involved in printing it. 		PDA made a good first impression by visiting our factory within 2 hours of our request for urgent assistance, and by demonstrating an obvious ability to understand our equipment. They had no problems liaising with our in-house author or working to established documentation standards even providing some useful suggestions for improvement.

Once the project was agreed, they just got on with the job, proving very willing to get thoroughly involved with the equipment, and competent to carry out dismantling, reassembly and set-up procedures. As well as writing the technical manual, they also actively contributed to the process of devising maintenance and fault-location procedures for what was a very new machine. We were extremely pleased by the service provided by PDA and would not hesitate to use them again should the need arise.

Tony Couling, Graham Labelling Systems

CONTACT US   © Publication Development Associates Ltd, 2007.   REDBOX DESIGN