· Introduction
· Preparation
· Writing process
· User documentation is about finding the best way of putting across technical information in a non-technical way to non-technical people.
· User documentation is difficult because it calls for communication between people with widely different backgrounds.
· User documentation does not necessarily require writing that simplifies the software. User documentation is best thought of as a type of writing that translates the computer activities for the benefit of users and readers.
· Its like translating a foreign language. When you are speaking to someone who shares a common background and language, they can fill in the gaps and make up for mistakes in your communication. However when speaking to someone who has a different background and speaks a different language, they cannot make up for gaps and mistakes, and need additional explanation (Brockmann, 1990)
Think of the difference between a programmer's reference guide and the user guide that comes with well known products like Word for Windows, Excel or PowerPoint. The first contains highly technical language and concepts, while the second is expressed in the kind of language the user is likely to understand.
Whereas technical writing catalogues facts in detail, user documentation should only say as much as is necessary to describe a step by step process. Too often, a document intended for user consumption is confused with technical writing, resulting in a document that is doomed to failure unless the user is willing and able to think like a technical person.
The computer industry suffers from a lack of good user documentation and it's the user who suffers. The software is written and then someone says, "Oh, and of course we'll need a manual". So, taking the technical specifications that the programmers used, someone puts it through a wordprocessor and it comes out the other side as the "user manual". The problem is that it still sounds like a technical document. The user takes one look at it, thinks to themselves "This is useless" and after that the manual stays on the shelf until it falls victim to a cleanup some years later.
On the other hand, large software companies like Lotus, Microsoft and the other big names spend a lot on their manuals in order for them to be "friendly" to the average user - that is, presented so that the user can easily find the information they need to get on with the job.
The same principles which the big software companies use to produce those manuals are given here. If you follow the steps outlined in these lectures, your manual will be of some use to the reader.
Digital Equipment Corporation (DEC), one of the worlds largest computer companies, noted in their 1983 internal documentation guidelines that user documentation should be written first - not last as is traditionally done - because the user documentation is an excellent way to debug the design of a system or program. If a writer finds it difficult to document a system, the problem is probably the system, not the writer. Holes in design, obscure constructions and apparent contradictions become starkly visible in the documentation.
Potential problem areas can be spotted early rather than after the product is finished. If problems are identified early, they are more likely to be fixed, since fixing problems later in the development cycle costs more money. In fact the later a problem is found, the more costly it becomes to fix. (Brockmann, 1990)
Most software products that can be described as being outstandingly good and/or user friendly have been developed this way.
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:
· All relevant specifications, record formats and screen and report layouts.
· An operating copy of the software, if available.]
· The analysts and programmers of the software, including the timely resolution of questions raised by you.
· Where available, typical users for audience analysis and usability testing.
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.
Develop the project plan using the following headings:
What will the title be. What is 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. Specify the usage mode of the document: Instructional - where the user needs to learn about the software. Instructional documents are either informational (i.e. tutorials and introductory manuals ) or task-oriented (i.e. quick reference manuals which give the steps the user needs to perform a task).
Reference - where the user needs to refer to information or refresh their memory and which give the information needed to understand the subject.
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?
Define the topic to be covered. What exactly do the users need to know? Do you 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.
Careful consideration of the nature of the audience allows you to choose the following:
· The best language to use.
· The right level of difficulty - not too difficult.
· How much material to include (so as not to overwhelm the reader).
· How to organise the concepts so that readers progress logically, beginning with what they understand.
When the manual will be widely distributed, its worthwhile keeping to the so-called "lowest common denominator"
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.
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:
· Blueprint.
· Research.
· First Draft.
· Language edit.
· Technical edit.
· Beta test.
· Final review date. Master copy ready.
· Manuals ready for delivery.
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.
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.
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.
The following ideas, many of them courtesy of Orwell can help you to use language as an "instrument of expressing and not for concealing or preventing thought". They apply to most kinds of writing, including user manuals:
· No tired figures of speech - avoid overworked expressions, cliches.
· Short not long words - never use a long word when a short one will do; use "timely" not "auspicious" or "opportune, use "set" rather than "predetermined".
· Specific, concrete word instead of a general, abstract one. Instead of: "We should request management to do something about their high overheads", say "Let's ask John, Susan and Peter to suggest five ways of cutting departmental costs".
· Economical - if it's possible to cut a word out without losing the meaning, always cut it out. en done to excess.
· Precise - with around 500,000 words (not including technical), English has perhaps the largest number of words of any language. With such a variety, try to choose the words which best express your thought. Many words have only slight differences in meaning; i.e. assisted, benefited, served, helped. Or meritorious, illustrious, distinguished, significant, renowned.
· Active not passive - always use the active voice where possible. For example it's better to write: `use the active voice' than to say: `the use of passive voice is to be discouraged'.
· Everyday English not foreign, jargon or scientific - except in situations where these are specifically called for, everyday English should be used rather than foreign, jargon or scientific words (i.e. not used for the sake of appearing knowledgeable).
· Prefabricated language _ avoid using "prefabricated" language. Rather than making the effort to think of new ways of describing things, most people lazily continue to use the same old expressions they've been using for years. For example: `At this point, the weekly invoice run is initiated and without further ado will run until finished.' Contains two pieces of prefabricated language; "at this point" and "without further ado'.
· Present tense not past/future - Unless it specifically applies, use present tense. Say "Pressing <enter> accepts the default value" rather than "Pressing <enter> will accept . ." (future tense). Another example, "use active voice in the present tense" rather than "the use of passive voice in the future tense is to be discouraged'.
· Avoiding overstatement - this general guideline applies to all communication. While there are few opportunities for overstatement in user manuals, it's still worth mentioning.
· Adapting words to the reader - to help the other person perceive what you're saying as interesting and intelligible. Certainly, using precise specific words adds interest as mentioned earlier, but you can also add interest by being concise and colourful in your phrasing.
· Never barbarous (advisory only) - despite the fact that opportunities to use "barbarous" language in user manuals are limited, it is still worth mentioning since it is perhaps the most corrupting use of language seen today. Governments use terms like "collateral damage" to describe the deaths of innocent people, or their own soldiers being killed by "friendly fire" (mistakenly killed by their own side), or "ethnic cleansing" used to describe genocide.
Care should be taken to avoid non-sexist (or non-discriminatory as it is legally known) language.
As a general guide:
· No gender assumptions - avoid using language which assumes a person's gender. Today, there are very few jobs where a person is always male or female. Instead of saying "he/she" or "they" when mentioning a person, refer to their job title or function, i.e. "the data entry clerk" or "the user" or simply as "you".
· Don't get carried away with removing apparent gender bias in language. With the best of intentions it can mutilate language. For example a "manhole" cover is the generic name of the object and to call it a "personhole" cover obscures it's meaning and leaves itself open to ridicule, whereas "access" cover is acceptable.
· Further information - if in doubt, consult the Anti-Discrimination Act and the Equal Opportunity in Public Employment Act relevant to your state.
Most people work best in a quiet, comfortable environment, as free as possible from interruptions and distractions. Easier said than done in many workplaces, particularly when the telephone never stops ringing and co-workers frequently want to chat.
It is important to arrange a time and a place during the working day where you can work in a quiet, interruption free environment, since you need to be able to concentrate and follow a train of thought for an extended period.
Get into the habit of writing everyday. It helps to reinforce the writing process and to overcome writer's block.
Schedule a period each day to work on the documentation and do everything you can to stick to the schedule. If your other commitments make it difficult to allocate time on a regular basis, discuss the matter with your manager with a view to reorganising your work load.
Since writing involves sitting in one position for long periods, certain ergonomic factors need to be considered. These include the following:
Provide yourself with a chair that gives good lumbar (lower back) support. Try to avoid slouching in the chair for long periods as this places strain on the lumber vertebrae.
The screen should be on or around eye level and not closer than around 40 centimetres. While no definite proof exists that this radiation is harmful to humans, many people do report degrees of discomfort and eyestrain. Common sense would suggest trying to minimise your exposure. Using an earthed radiation shield is recommended.
The intensity of radiation coming from a screen decreases rapidly the further away the screen is. Therefore, position the screen to be as close as it needs to be to allow your eyes to comfortably read the words on the screen, and no closer.
Occupational health guidelines recommend taking a break every hour by getting up and walking around. This not only helps your circulation and eyes, it also clears the mind.
Return to Technical Communication Resources Page | Return to CIT Home Page