DOCUMENTATION FORMS
Quick start guide - How to carry out basic, common tasks encountered when starting to use the system
You probably immediately think of printed training manuals when you think of "documentation" but there are several different forms for different occasions.
Good documentation
Good documentation should be:
Clear: able to be understood by whoever it was created for. The language used must be appropriate (not too complicated; controlled use of jargon). See Electronic Publishing for more information. Terms that may not be understood by everyone need to be explained either the first time they are used or in a glossary.
Concise: it should be as short at it can be while still being comprehensive. Using pictures (such as screenshots) can replace hundreds of words and be much clearer at the same time. For example, how would you describe the following button to a reader if you had to use words?
(In case you're curious, it's the "View Desktop" button from a "File Open" dialog box.)
Complete: it should not leave out important information (especially key steps that need to be completed, such as printing, and warnings about what not to do)
Current: it's no use if all the facts are out of date or superseded. Printed material is harder to keep current than electronic versions are.
Correct: it must not contain errors
Easy to access: it must be available where and when it is needed. This can be a problem with printed material, especially if the books are expensive and many copies are required.
Easy to search: users must be able to quickly find the required information. Indexes or tables of contents are required, along with clear headings. Large documentation may well need to be divided into sections. You might get a little "Installation" brochure. Then there may be a slim "Getting started" introduction. Then there may be a separate users manual. Then there may be a technical reference. The idea is that different users need different sorts of information at different times and they don't want a massive single book to plough through to find it. Really gory technical information could scare beginners. Technicians don't want instructions like "This is a mouse." getting in their way when they're troubleshooting IRQ conflicts. Novell Netware even comes with a separate volume that is an index to all the other volumes.
Printed
The traditional format for documentation, it is used much less nowadays. Printing is expensive and books are heavy and bulky, which increase transportation costs. Books are hard to keep up-to-date if their subject matter is subject to change. Books can only be accessed by one person at a time.
Onscreen help
Most programs come with online help that can be accessed immediately by pressing F1. It is readily accessible, searchable and can be very detailed.
Help can also be gained from online sources such as the internet and intranets. Such sources can easily be kept up to date - even on a daily basis. They can be accessed by any number of people simultaneously.
More and more documentation is appearing in web-page format even if it's not going to be used on the internet: everyone has a browser, web pages are colourful, hyperlinks connect related topics, they are very easy to update and maintain. Of course, they can also put on the internet or an intranet with no hassle. Consider HTML for your next instruction manual!
Audiovisual
Videos, screen movies, audio narration etc. Colourful and engaging but do not tend to carry a lot of detailed information. Good for introductions or overviews of subjects.
Posters, leaflets etc
Sometimes detailed information is not needed. A checkout chick, for example, does not need wiring diagrams for the circuits of the register. She may just need a little poster that quickly reminds her how to do basic tasks (especially things that don't happen often and may slip the worker's mind). Troubleshooting tips may be useful.
Why it's hard to write documentation for international audiences
