The Project Handbook: How to Write Clear and Cogent End-User Documentation
Jinfo Blog

By Stephanie Taylor

Item

Mention project documentation and the usual set of documents aimed at keeping things on track come to mind: the project plan, initiation document, reports. In short, all the documents designed for the project manager and project board.

But there is a forgotten audience just as important to the success of the project. These are the people who will ultimately be working with the innovations being introduced. They may be staff within an organisation, end-users or both, depending on the nature of the project. They will have one thing in common: they will know very little or even nothing at all about the project itself prior to their active involvement.

As these users are often involved in testing and trialling the innovations, it is in everybody's best interests that they know about the project and understand what is expected of them. The development or introduction of new technologies is especially vulnerable to failure if these people are not confident of the project aims and their own role within it.

Without clear guidance, it can be difficult for people coming into the project at a later stage to understand the aims and objectives. Identifying whether a problem is technical, operational or a training issue can be all but impossible. And projects can falter and even ultimately fail not because the technology wasn't suitable for its purpose but because the users failed to understand how to use and apply the innovations in their working environment.

Having worked on many projects large and small, I have devised a project handbook, a kind of reference book to cover the needs of this group. The secret is to understand where the project will fit into their current workflow. Keep the document focused on the practical side of things. Do this by creating a reference book and a how-to guide in one. For easy use, include everything they might need to actually carry out their tasks and leave out anything that isn't strictly relevant to that purpose. The following guide is the one I use myself for starting any project handbook. It is flexible and can be adapted to suit your needs. It easily scales up or down depending on the size and scope of your project.

Part 1: Research and scoping

The first step to any good end-user documentation is to identify who will be in this group as early as possible and start talking! Talk to them about what they do, what you want them to do and where the changes your project is initiating will fit in with their work.

This step helps people feel a part of the project, and it introduces the new ideas to them well in advance of the implementation. At the same time, you build an understanding of the way they are already working and can start looking at how your project will fit in on an operational level.

Answering the following questions is a good starting point:

• Is your project introducing something totally new to the users?
  
  
• Is it changing the way they do an existing task?
  
  
• Are you introducing new technology, a new service or both?
  
  
• Are there any other technologies that your project will interact with?
  
  
• Are there any other operational procedures that your project will interact with?
  
  

In your project handbook, it is useful to include a description of what the workgroup used to do along with what they will be doing in the future. This helps put changes into context. For example, any UK- based library document delivery/ILL system will handle requests to the British Library (BL), but will it handle them in different ways. For a project that is introducing changes to the technology in this area, you should be looking at how the users interact with BL now and how the workflow introduced by your project will interact with BL in the future.

You would need to check the following:

• Is there a technical change to the way requests are sent and responses received?
  
  
• Is there an operational change to the way staff process requests?
  
  
• Are there any new operational options (e.g. may end users be able to place requests themselves for the first time)?
  
  
• Does the requesting process interact with any other technologies (e.g. does it need to link into a library management system)?
  
  
• Does the requesting process interact with any other part of the operational procedures (e.g. do staff work to an agreed service level turn-around time, and is this affected)?
  
  

Identifying the key areas for the whole workflow of the project application will ensure that your handbook explains in detail what is going to happen and what users need to do.

Part 2: Creating the handbook

The following contents checklist covers the basics of what should be included in a good project handbook. It can be adapted to suit any project.

Project overview

The handbook itself should be essentially a user guide. Focus on making everything in it practical. Remember that several other documents detail the various plans and ambitions of the project, so write a short introduction section only. Refer your readers to any documents that cover other project areas in more detail.

Scope

The scope is a short section but a vital one and should explain the current phase of the project. This is especially useful if you are releasing a partial version of something to your users. Explain what they will see now and why. If there are new features to come in later project phases, put what they will be doing in context of how the project will develop. Explain the purpose of what users are being asked to do. Are they testing? Checking through for acceptance? Piloting for a wider 'go live'? Make sure they understand what the project is doing in this phase and their role in it. Include start and finish dates as appropriate.

Step-by-step guide

This will be the largest section of the handbook. It should cover both technical and operational procedures in minute detail, so someone can follow what should be done step by step. Divide this section into manageable sub-sections so it can be easily updated. Refer to anything you found out from your preliminary research. You are aiming to leave no grey areas here. Even if your project is undertaking training sessions for users, don't skimp on this section. It builds confidence for users to know they can refer to the handbook at any stage and see what they should be doing. Change is often a worry for people. This section is where you reassure users and guide them through everything that is required of them. The more confident your users are, the more chance your project has of succeeding.

Checklist of requirements

This is a list of everything users need to participate in the project phase. Include any basic things like equipment, logins, internet access and permission. Include project-specific information such as software versions, technical specifications, agreements with third parties and pre-start testing. These details are usually sent out many times in many formats before the users are involved, but your handbook is going to become the place they turn to for help, so include them here.

Contact details

Always include ways that users can contact you when they are working with the product in the project phase. The handbook should answer most of their questions, but there is bound to be someone who thinks of a question you haven't covered. If the handbook can't answer it, make sure they know where to come for more help.

Feedback

Let your users know how they can send you their comments and impressions of the project. This could be a printed form or an email address or an online form. Including details for feedback lets the users know that you are taking their input to the project seriously. The more feedback you get, the more you know about what works and what doesn't. Make it clear that you view comments -- good and bad -- positively!

Next steps

Every project has next steps, be it the next phase, a refinement of acceptance requirements or going live. Tell the users what the next phase will be, what the schedule is and when they can expect to have updates. This keeps them interested and gives them a sense of moving forward. If things change, you can update them. Including this information means users can see progress and sense that your project has a purpose.

Part 3: Maintaining momentum

The comments and suggestions you solicit will give you a good idea of what is working, what isn't and where improvements can be made. As decisions are made about how these will (or won't) be incorporated into the project, let your users know about any practical changes that occur. Remember that you are dealing with the way people are working on a day-to-day basis even if your project is just asking the users to do a dry run. So make sure that you update the step-by-step guide frequently. Make the most of the subsections you created, and send out replacement pages or subsections as required on an 'as and when' basis. Users can than replace the old sections easily to keep the handbook up-to-date.

In addition, decide if you need another version of the handbook. If your project is going to have users participating in further stages of testing or is scheduled to go live, then a new version of the handbook is a good way of keeping everything current. Use this as an opportunity to make any updates and revisions from feedback you had from the previous version, to add any amendments and appendices into the main text and start with a new definitive guide for the next project stage.

Done well, a project handbook should cut down on helpdesk calls and focus feedback on useful comments rather than complaints along the lines of: 'I didn't understand ...'. It can save time for all concerned and make the users feel they have a useful and important role in the project. It can give users the confidence to take on the challenge of change your project is introducing into their workplace. Once people are sure of their own part in things and what is expected of them, it frees them up to concentrate on giving new ideas and work practices a fair chance.

Don't be surprised if a well-thought-out handbook becomes a prominent part of the project for the users. In the best instances, it becomes not only a useful guide but also makes the users feel a part of things. It can become the contact point of the project for them, the hub around which the project activities revolve.

Related FreePint links:

• "The Product Development Cycle" By Stephanie Taylor. FreePint No.140 <http://www.freepint.com/issues/100703.htm>
  
  
• "Developing Web-Based Instruction - Planning, Designing, Managing and Evaluating for Results" <http://www.freepint.com/bookshelf/instruct.htm>
  
  
• Documentation Design discussion in the FreePint Bar <http://www.freepint.com/go/b5007>
  
  
• "Enabling End-Users: Information Skills Training" <http://www.freepint.com/bookshelf/enable.htm>
  
  
• XML Documentation Tutorial in the Microsoft Developer Network (MSDN) Library <http://digbig.com/4mxhc>
  
  

« Blog