|
Types of Documentation |
||
Documentation has traditionally taken the form of printed manuals, generally A4 or A5 size, printed either double- or single-sided. This type of manual still has a part to play but is now largely superseded by on-screen documentation. User guides and similar paper documents have slimmed down to an alarming degree or have disappeared altogether as they are replaced by other formats.
Types of documentation and their features are as follows:
Click here to see a typical structure for a printed manual
Apart from their usefulness in propping open doors and other vital tasks, these have the advantage of familiarity. They can be consulted away from the computer, although they are not recommended as holiday reading. Manuals are still the preferred method for many and, indeed, the first thing some people do with online documentation is to print it out.
Printed user guides do, however, require good indexing and an adequate table of contents to make them usable. They are notoriously difficult to update, especially when there are several large manuals, many users and frequent system revisions.
This type of documentation can be printed in-house or by TechWrite Services, providing that volumes are reasonably low. For longer print runs, PostScript or PDF files are produced and sent to a print bureau for final production.
Click here for an online help example
Sometimes this may be a converted version of a printed manual that is provided on-screen. However, there are significant differences between the structure of printed and online documentation (this is discussed later at Printed versus Online).
Readers may access help text as a whole document but can use hypertext links to navigate around the text and may have a table of contents and index entries to find particular items of interest. It is often provided as a 'context-sensitive' structure — system users go directly to the relevant topic by pressing a help button or the F1 key.
Online documentation is revised by reissuing the whole document on CD or similar media. You could post updated versions on your website for registered users to download.
Online help text is provided as many types, which can be used in different circumstances:
WinHelp has been part of Windows since version 3.0 and has been the standard form of help text through Windows 95 and NT4. It is now superseded to a large degree but is reasonably fast, compact and has full contents, word search and pop-up features.
Compiled HTML Help started from Windows 98 and is included as part of the operating system. It matches many of WinHelp's features and is very common. Topics are compiled into a single help file which, depending on the size and complexity of the subject being described, can become quite large.
Generic HTML is the language and file format used for web sites
and so is widely available, well supported and is accessible using many
browsers. It normally comprises many small files, one for each topic, which
are linked by a contents file. Consequently, this format is ideal for remote
access since it does not require large files, such as those produced for
compiled HTML, to be downloaded. However, it has limited navigation features
and no search capability.
JavaHelp offers many features of HTML Help and WinHelp. Most modern browsers support Java.
Various sub-types can be provided for some types of help — dynamic help that changes as the user processes the associated application and 'What's This?' help that gives a description of a specific screen feature, for example.
Printed manuals and online help have different features and require separate production methods:
|
Paper-based
|
On-screen
|
| Page-based with numbered pages, headers and footers, and page breaks at logical points. | Topic-based, with each separate topic described on a single scrolling screen. |
| Embedded cross-references to other sections and pages. | Hypertext links between topics. |
| A printed index connects selected phrases to the pages on which they appear. | Searching by single words or phrases. |
| Users may read pages in series on connected topics. | Topics need to make sense 'out of context' since users may access them in isolation. |
| Large range of fonts available. | Fonts are limited to those on users' machines and should generally be sans-serif and non-italic (otherwise they may be difficult to read on screen). |
| Chapters and sections are usually numbered to provide precise cross-referencing and to allow page numbering within chapters (this avoids the need for a complete reissue of manuals when chapters change). | Topic numbering is not necessary since navigation may be by on-screen contents list, word searching, and hypertext links. |
| Sample screens and reports are generally included, since they provide a useful visual reference for users. | Users access help text directly from applications and so sample screens are not always necessary. Screen resolutions can sometimes cause graphics to appear jagged and indistinct. Additionally, limited display areas may push associated text off the screen. |
These types of file are produced through Adobe Acrobat but can be read using the Acrobat Reader, which is distributed free. The advantage is that, however a document is produced, it can be viewed and printed on any machine under any relevant operating system and retains the same appearance.
PDF files can be distributed over the Internet or a company Intranet. These files are often provided instead of printed manuals so that users can, if they wish, print the documents. They are also accepted by print bureaux to produce printed output.
These are another form of online help and are an alternative to 'What's This?' help. They provide pop-up boxes of information that appear automatically when the mouse cursor hovers over an area of the screen where a tool tip is set. Tool tips are ideal, therefore, to provide a description of an input field or the purpose of a button, but probably not for a whole screen or program.
In effect, the type of documentation you produce may depend on a number of factors. These can include such considerations as where the readers are based, the platforms they have, and how they will use the documentation.
A mixture of the different types can be produced for your product. Thus:
a printed Getting Started Guide or brief system overview
help text that describes the individual routines and how they are used; this may be compiled HTML for local users and generic HTML for those at remote sites
tool tips that deal with input fields and buttons.
Providing documentation of the appropriate type will cover the system in the correct level of detail at the appropriate point. All relevant points and topics will be dealt with, while avoiding unnecessary duplication.
 |
 |
 |
Copyright © 2000-5 Jeff Senior, TechWrite Services Telephone/Fax 01924 409563 E-mail admin@techwriteservices.co.uk