This chapter covers the range of activities you need to perform in order to establish a good foundation for your documentation project. The importance of good preparation can hardly be emphasised enough - it is vital to the success of any documentation project, particularly larger projects.
The object is to clearly define the finished product before beginning to write. If you do this, and get approval for your concept so that the project manager and yourself both expect the same thing, you will avoid the need to re-do sections of the manual later.
Much trouble can be avoided by having a clear agreement between yourself and the project manager as to what the finished product will look like and contain. Assumptions should not be made since they are usually not shared by the parties.
It is important that all source material necessary for a thorough treatment of the subject be made available to you at the outset.
Source material includes the following:
While it is your responsibility to communicate accurately the source material to the user, you are not personally responsible for the accuracy of the original source material.
Where documentation standards already exist, you need to be supplied with copies of the relevant standards. Otherwise, use the standard outlined in a later section of this manual.
Source material received by you is normally on a loan basis. You need to keep it in good order and return it when finished. In some cases the information might be confidential. In these cases, you will need to sign a non-disclosure agreement.
It is necessary to develop a project plan. This is done in two stages. The first stage is to be briefed by the project manager or someone delegated by them as to the exact nature of the job ahead. The results of the briefing is a mutual understanding of what is to be delivered by when.
Prepare a document called "Preliminary Project Plan" using the headings which follow. This will form the basis of the final project plan which can't be developed until the following information is gathered and considered.
Getting answers to these questions allows you to develop a suitable project plan.
When you have finished the preliminary project plan, discuss it with the project manager and after any amendments which might arise from those discussions, it should be signed-off or otherwise formally agreed by both parties. This might seem an unnecessary formality however from experience its value as a benchmark for future reference is undoubted. It also obliges the project manager to provide you with everything you need to complete the project - this sometimes comes in very handy.
Once the preliminary project plan is complete and it has been signed-off, a detailed project plan is developed.
Using the preliminary plan as a basis, develop the project plan using the following headings:
Decide on a name for the manual. Be guided by the subject matter and the intended audience. Be as concise as possible when describing the purpose. A manual can also be called a handbook or a guide.
For example, "CMS User Guide" is more concise than "Complete Guide to the Construction Management System".
A clear statement of the purpose of the document. This will start with what you put in the preliminary plan, together with any amendments which might have arisen from your discussions with the project manager.
Specify the usage mode of the document. The usage mode of any user documentation can be divided into two broad categories - instructional and reference:
It's important to decide the usage mode at the outset. Without this definition, the manual will probably be a mixture, alternating between modes, confusing the reader. On the other hand, the impression of consistency inspires confidence in the document - something you desperately want if the manual is to succeed.
An instructional mode document should give the background information needed to understand the system, and also give details of the range of functions the software can perform and how to perform them. Examples are given to reinforce the learning process.
The Informational type of instructional document provides background and any technical detail needed to understand the system. This would include a system overview, a theory of operation and a tutorial. The technical information should be provided by the people who developed the system.
Task oriented instructional documents outline the procedures of operation. Examples of this kind of documentation include a diagnostic procedures manual (i.e. troubleshooting manual), operations manual and software installation manual (getting started or read this first).
Reference mode documents organises information that users might need, and allows quick access to details of specific subjects. Examples of reference mode documents include a command manual, error messages, program calls, quick reference guide, software tools and utilities.
Outline the draft table of contents.
Specify how many printed copies are required, whether disk copies are to be supplied, the disk and file formats (including software versions) and where and when they will be delivered.
Specify the project resource requirements, including what information is required from who and when. Who and what resources are to be made available?
What source material, written information is to be made available. This includes requirements list, specifications, reports etc.
What is the nature of the software? Is a working copy available for you to use? For example is it for accounting, inventory, personnel or perhaps to control a production process? Define the nature of the software in terms of it's functions. What is it for exactly? Then consider the kind of user interface it employs and the type of work that users will perform with it.
What is the scope of the project? Are a complete set of manuals required which detail every aspect of the software, or would it make more sense to document only those parts which people will use? Consider the benefits against the time and effort that will be needed.
The documentation needed depends on the nature of the software product, how it is applied and who will be using it. Once you've identified these, the document sets for the intended users can then be determined.
Define the topic to be covered. What exactly do the users need to know? Do we want to provide background information to help them understand what's happening behind the scenes, or just tell them enough to do the job? Cost can be a major consideration here.
Think about exactly who will be using the documentation. This tells you what assumptions can be safely made about how much the user already knows, and the kind of language they will understand. For example a manual which will be used by accounting staff will call for different language than a manual used by station staff.
Think about the different ways that the user will interact with the software. Will they need to interact a lot, and at what kind of level. For example, does the software simply require fairly simple responses or will it need whole screens full of information to be entered? The answers to these questions determine the presentation style and the amount of detail.
In some cases, it may simply not be worth producing full documentation. For example a handful of highly technical users might need a relatively short manual so it would not be worthwhile producing a very detailed set of manuals in this case. On the other hand it would be worthwhile for non technical users, particularly where there are more than a handful of users.
Careful consideration of the nature of the audience allows you to choose the following:
When the manual will be widely distributed, its worthwhile keeping to the so-called "lowest common denominator" i.e. the person with the least amount of knowledge or expertise. Following this principle makes sure your manual reaches all the people it can.
A set can be a single document or several documents, depending on how much detail is to be included and the needs of the audience. For example, a set of user documentation might be made up of a two volume reference manual and a training manual. The training manual is clearly separate from the reference guides which have been broken into two since to have one large volume would be unwieldy.
Where a document set needs to cater to widely differing needs, it's necessary to either include different sections for the specific audiences with that audience being clearly mentioned in the introduction, or to simply produce different documentation sets for the specific audience.
The layout and design of the document is outlined in detail in the later section "Document production". Is the document to be written according to any standard or specification?
Develop a schedule showing the milestones, as follows:
Indicate the software tools you propose to use for the project. Whatever your choice, as a minimum requirement, the various packages need to be compatible with each other. Some graphics packages, for example, won't deliver useable images to some wordprocessors.
To avoid potential problems, stay with tried and proven software solutions or seek the opinion of knowledgeable people whose judgement your respect.
Specify who will retain editorial control over the document.
Specify who will perform the technical edit.
How much will the documentation project cost, or how much is being allocated for the documentation.
Who has ownership of copyright and any other proprietary rights. Usually, the author of a commissioned document is the first owner unless a specific agreement otherwise. If the customer is to own the copyright, it must be assigned as part of the contract between author and customer.
What provision is to be made for the translation into other languages, if applicable.
Estimating the time and resources needed to successfully complete a documentation project can be a difficult procedure for the inexperienced. It is easy to underestimate. Estimates can be overrun if the software changes during the course of writing the manual.
The Minutes and Hours estimating method outlined below works on the assumption that it takes around three hours per page to write text to publication standard. The time needed to design graphics is determined by their complexity and the number of redrafts needed to ensure their technical accuracy. On average, the kind of graphic commonly found in user documentation will need three to five hours to design and amend. Graphics in this sense do not include screen images.
Knowing how long each page is likely to take does not help you to determine the likely number of pages. This needs to be done using a combination of common sense and a shrewd appraisal of the number of software functions to be documented. Your estimated page-count should be reviewed a fortnight or a month into the project.
When undertaking a large project, the deliverables should be split into manageable parts. The estimated time to complete the entire project would then be given in terms of whole months, with the first part being the only part worked out in detail.
The table below shows average times to complete the various stages of the project. It assumes the writer is entering the text directly into a PC and that desktop publishing is used.
Stage Time
Determine deliverables 16 hrs /
project
Research content 24 hrs /
project
Write documentation plan 48 hrs /
project
Design document structure/page 8 hrs / project
layout
Write first draft 1 hr / page
Develop graphics 5 hrs / graphic
Compile text and graphics 30 min / page
Review 1st draft for technical 30 min / page
accuracy
Amend draft and graphics 30 min / page
Conduct user reviews (customer) (customer)
Incorporate user comments 30 min / page
Edit grammar 15 min / page
Prepare second draft 15 min / page
Review second draft (customer) 15 min / page
Make final corrections 10 min / page
Test documentation 15 min / page
Arrange camera-ready art 3 days
Print binders/tabs 5 days
Print and collate copies (B & W 10 days
only)
Distribute 1 day
This is the end of chapter 2. Remaining chapter include:
To order your copy, click on HOW TO WRITE USER MANUALS
Copyright © 1996 - 2009 Tuffley Computer Services