On-line documentation for the software user
A review of the literature
Door Herman Gritter, Enschede, June 1993 (gereviseerd 14 okt. 1997). Supervision: R. Min & J. Moonen
Literature review for the Faculty of Educational Science and Technology of the University of Twente
Preface
To graduate in Instrumentational Technology at the faculty of Educational Science and Technology I have conducted three activities: an assignment in the design, development and evaluation of educational software at the University of Southampton, an internship combined with this assignment and a literature survey on the subject of on-line software user documentation. The result of this last activity can be found in this report.
1. Introduction
In this literature review some aspects of on-line software user documentation will be discussed. In this chapter first attention is paid to the problem definition. Second, the method of literature search is described.
1.1 Problem definition
The purpose of this literature review is to find an answer on the question:
'What precisely is on-line software user documentation?'
In order to answer this question the elements of the concept 'on-line software user documentation' were analyzed separately. So, first an analysis of literature about 'on-line documentation' and related terms has been conducted. Starting questions were:
- What definitions are there for on-line documentation and related terms?
- What are the differences between on-line and paper-based documentation?
- What are the advantages and disadvantages of on-line documentation
Second, an analysis of literature about different types of on-line documentation has been conducted. The question that was put, was:
- What types of on-line documentation are distinguished?
Third, an analysis of literature about the software user or the audience, and what sort of documentation the different types of software users need has been conducted. The next questions were asked:
- What audiences are distinguished as we talk about on-line documentation?
- What types of on-line documentation go with what type of audience?
These question were all asked in order to find an answer on the first question. Finally some attention has been paid to possible developments of on-line documentation in the nearby future.
1.2 Method of literature search
The literature search was conducted in two different ways. First, with the help of the catalogue system of the university books were selected on words in the title. The first search-word was 'HELP', with one useful title. Hereafter a search was conducted with the words 'DOCUMENTATION' and 'ON-LINE', again there was one useful title.
Second, on basis of these two titles the snowball method was used. With the snowball method references and the bibliography of a book are used to select other readings. These other books or articles are analyzed and again the references and bibliography was used to select useful books or articles. This procedure was repeated until enough information was gathered.
2. On-line documentation
In this chapter some aspects of on-line documentation are analyzed. First, definitions of on-line documentation and related terms are presented. In the first paragraph there is as well some attention paid to the reason why on-line documentation is needed. Second, the differences between on-line documentation and paper-based documentation are analyzed. Third, the advantages and disadvantages of on-line documentation are described.
2.1 Definitions of on-line documentation
In the literature we find several definitions for on-line documentation and related terms, which are all slightly different. In this chapter a number of these definitions for on-line documentation and related terms are presented. Houghton-Alico (1985) provides us with a definition of 'on-line':
'Working directly under the control of the computer's central processing unit; also, a user's direct interface with a computer.'
For the term 'on-line documentation' numerous definitions are available. Below a selection of the definitions is presented. It has to be noticed that these definitions differ on some aspects. Cohen and Cunningham (1984) define on-line documentation as an electronically stored user manual:
'Instructions for running a program on a computer screen, information that ordinarily would be published in a traditional manual.'
Kearsley (1988) makes a distinction between on-line documentation, on-line help, and on-line training. On-line documentation attempts to explain something and therefore is descriptive. With on-line help the information is focussed on a specific problem. On-line training tries to facilitate learning. The instruction for all three could come from the same database, but it may be presented in a different way to the user. Other authors don't make a distinction between these three. Horton (1990), for example, defines on-line documentation in a wider perspective:
'On-line documentation includes the use of the computer to communicate information that might appear in print, but it does not stop with electronic analogs of paper documents. It also includes types and organizations of documents not possible on paper and incorporates non-paper media such as animation, voice, music and video. On-line documentation uses the computer chiefly to communicate information, regardless of the format or subject matter or of whether the information exists in other forms as well. It is the computer used as a communication medium, instead of as a number cruncher or word-processor.'
According to this definition even news-papers stored electronically are on-line documents, and as well computer based training for learning a language. Horton (1990) adds something more to this definition:
'On-line document systems have two essential parts. The first is electronically stored information. This is most often text, but may also include illustrations, voice, other sounds, animations and video. The second essential component is a means of accessing that information.'
Brockmann (1990) provides us with a definition of on-line documentation that is more specific than the previous one, but more general than the definition presented by Kearsley. The definition below specifies on-line documentation to documentation especially for computer software:
'Communication designed to be presented on VDT screens in order to ease interactions between computer software and individuals who manage, audit, operate or maintain it.'
In the literature we find some other terms that are related to the term on-line documentation. With the help of these terms it is possible to get a clearer perspective on what on-line documentation for software users is. In the IEEE Standard (1988) software user documentation is defined as:
'Body or material that provides information to users; typically printed or stored on some medium in the format of a printed document'
In this definition no distinction is made between on-line documentation and paper-based documentation. Next it is clear that, according to this definition, on-line documentation is information stored on the computer in the format of a printed document. Houghton-Alico (1985) uses the term software documentation, and describes it as follows:
'Software documentation is the collection of documents that explain, describe, and define the purposes and uses of a particular software program or a system made up of multiple programs.'
Next to this definition Houghton-Alico (1985) described the term 'on-line interactive documentation', which is more specific than on-line documentation:
'On-line interactive documentation is data accessed on a computer system that helps end users utilize software programs correctly. It also may be called 'electronic documentation', 'embedded documentation, or 'electronic users guides'.'
Now that there is some clarity about how on-line documentation is described in the literature it is time to indicate some reasons behind on-line documentation. Brockmann (1990) sums three reason why on-line documentation is needed:
- To improve efficiency: personnel changes are frequent so they (producers of software) cannot afford to depend on word-of-mouth information.
- To overcome users' fears of equipment or software: successful software documentation leads to successful first encounters with software and, therefore, to greater acceptance and use.
- To sell the product.
2.2 Differences between on-line documentation and paper-based documentation
In the literature we find some clear statements about what the differences are between on-line documentation and paper-based documentation. Here it is only described what the differences are according to the authors. It is not tried to make a judgement about which of the two is best. Probably on-line and paper-based documentation can exist next to each other and are supplemental to each other.
According to Horton (1990) paper-based documentation and on-line documentation differ in they way they are organized:
'With paper documents the content , format and organization are indelibly bound together. Whereas on-line documents have totally separate content, format and organizations and the designer (of the on-line documents) must manage each element separately and in combination.'
Shirk (1988) and Carlson (1988) agree with Horton. On-line documentation is not just a paper-based document dumped on-line:
'However one chooses to label it, on-line documentation is not paper-based documentation placed on the computer for access through a computer terminal. Rather it is documentation written specifically for access only by means of a computer terminal.' (Shirk,1988)
'The industry trend is toward more on-line documentation and many installations have began converting off-line materials to on-line. However, simply putting existing text on-line is not satisfactory because accessibility and ease-of-use are seriously impaired.' (Carlson, 1988)
According to Brockmann(1990) on-line documentation goes beyond the limits of traditional paper manuals because it integrates text, graphics, animation, sound effects and database organizational schemas. On-line user documentation solves four other problems that appear with paper documentation. These are the static organization, the often massive physical appearance, the passive role for the audience (manuals are only used when there is a problem), and inconvenient packaging. Brockmann (1990) indicates as well a rhetorical difference between on-line and paper-based documentation.
'On-line documentation has no inherent physical analog to its organization and structure. Thus readers are lost much more easily in the organization of on-line documents because they cannot sense its structure.' (Brockmann 1990)
But, all of this doesn't mean that paper-based documentation has no value at all. According to Brockmann (1990) 75% of the techniques and ideas of effective paper documentation are transferable to on-line documentation.
Next, the question can be asked whether or not users, who use on-line documentation, perform their task better than users who use paper-based documentation. From research conducted in 1982 by Cohill and Williges (in: Kearsley, 1988) it seems that there are no significant differences in performing a task when using help presented on-line or using help presented on paper.
2.3 Advantages and disadvantages of on-line documentation
In the literature a number of advantages of on-line documentation are mentioned. These advantages vary from the way the information is presented to the convenience of the packaging of on-line documentation.
The first advantage of on-line documentation is that it is available whenever the computer is available (Shneiderman, 1987; Houghton-Alico, 1985). It is clear that because the information is stored on the computer the information will not get lost - only if it is deleted accidentally - or left behind at home or in the car.
A second advantage that is related to the previous one is that the documentation can be kept current with the program more easily than other forms of documentation (Houghton-Alico, 1985).
A third advantage is that the user doesn't need to allocate physical workspace to opening up manual (Shneiderman, 1987).
A fourth advantage is about the costs of todays software accompanying documentation. The economics and logistics of producing, distributing, and maintaining conventional technical manuals are becoming prohibitive (Cohen & Cunningham, 1984). Next to that, the information can be rapidly updated at low cost (Shneiderman, 1987).
A fifth advantage is the quick access to information. According to Cohen and Cunningham (1984) is the machine the only thing that can keep up with the speed of the machine. Putting the information on-line enables the operator to retrieve information at electronic speed. Shneiderman (1987) indicates that if there is electronic indexing the needed information can be located rapidly.
A sixth advantage is about the way the information is presented. On screen graphics and animations can be shown that may be important in explaining complex actions (Shneiderman, 1987; Brockmann, 1990).
A seventh advantage is the physical relation between where the information is stored and the subject of that information. The information is related directly to the context in which users are working (Houghton-Alico, 1985). Cohen and Cunningham (1984) present a metaphor connected to this advantage. A person learns to drive a car by actually driving it, not by reading a manual. The same thing is true of any machine, including a computer.
The eighth and final advantage is about how people want to receive information and about how they want it to be presented.
According to Cohen and Cunningham (1984) there is an increasing reluctance to read technical manuals. People today want to receive information faster and in a more graphic and interesting form.
Next to these advantages there are as well disadvantages or drawbacks on on-line documentation. Some of these disadvantages or drawbacks are not applicable on every today situation in which on-line documentation is used. If this is the case it will be mentioned.
The first disadvantage that is mentioned is that the screen is also used for other work (Shneiderman, 1987). On-line documentation frequently fills a screen with information that 'loses' work the user was doing (Brockmann, 1990). Here it is clear that with the multi-tasking and windowing technique it is not necessary that an on-line document fills the screen completely.
A second disadvantage refers to the lack of realism of pictures and the lack of resolution of the computerscreen. Shneiderman (1987) indicates that screens are not as readable as printed materials. Cohen and Cunningham (1984) say that computergraphics are not as realistic as in print and video, because of the resolution, that is the pixelsize on the computer, of the screen.
A third disadvantage concerns the amount of information that is visible on a screen. According to Shneiderman (1987) is the amount of information displayed on a printed page larger than displayed on a screen.
A fourth disadvantage is that the presentation of information has to be matched to the medium (Cohen & Cunningham, 1984). So, the information that is already available has to be organized different, and some access aids have to be developed as well to access the information.
A fifth disadvantage concerns the lack of enough access aids. Brockmann (1990) indicates that the on screen the number of traditional reader access aids are reduced. On-line documentation frequently give only a hierarchical tree structure of menus, just a keyword search or just a browser to access information.
A sixth disadvantage concerns the physical appearance of on-line documentation. The problem with this is that a traditional manual can be reviewed at any time it is convenient, but a computer can be busy so you cannot read the on-line manual and you cannot take a terminal home and read the on-line manual (Cohen & Cunningham, 1984).
Overall it can be indicated that on-line documentation is not a heaven on earth. Some advantages are at the same time a disadvantage, for example the physical appearance of on-line documentation.
3. Types of on-line documentation
In this chapter first a number of different types of on-line documentation are identified. Next these types are categorized into four categories and described.
Shirk (1988) categorizes the various types of on-line documentation as moving from relatively simple to complex writing. The 'Taxonomy of On-line Documentation' presented in figure 1 shows this hierarchy of increasing writing difficulty.
Figure 1: 'Taxonomy of On-line Documentation'
Kearsley (1988) makes a distinction between the three types, of which one is on-line documentation. The other two are help information and on-line training. The way Kearsley describes the term on-line documentation does indicate what he means with it. On-line documentation in his terminology is more or less the same as a reference guide, or a command reference, and so on.
Houghton-Alico (1985) distinguishes three types of software documentation: technical documentation that provides background information on the initiation, development, and operational phases of the life cycle of a particular software program; product documentation is the bridge between technical documentation and user guides; and user guides. Possible formats for user guides include the following:
- hard copy (e.g., manuals, reference cards, posters);
- on-line (e.g., program comments, interactive prompt and menus, macro or shortcut instructions, interactive training programs);
- media (e.g., audiotape cassettes, videotape, video discs, other audio visual training materials);
- personal (user groups, one-on-one or group training).
Rubens and Krull (1985) distinguish some types of on-line information, ranging from error messages to tutorials.
Foehr and Cross (1986) look at documentation out a number of different perspectives. First, documentation is the bridge between two systems: human and machine. Documentation provides an orderly step-by-step explanation of a complex system to a user who knows nothing about that system. Second, documentation is a map that charts unknown territory for the user. Third, documentation is a sales tool. The documentation must satisfy the customer's desire to know what the system is capable of doing. Fourth, documentation is a training technique. Fifth, documentation is a reference guide.
Min (1992) distinguishes eight types of parallel instruction, that is instruction running or given concurrently with software, in his case a computer simulation program. The forms of parallel instruction that are on-line, are CBT, help and video and audio recorded for the computer.
Foehr and Cross (1986) distinguish six types of documentation of which only two are mend for external, that is for people not working in the producing company, use. These two are: operations documentation and the user's manual.
In the IEEE Standard (1988) a distinction is made between documents which are needed either to learn (instructional mode) or to refresh (reference mode). In the instructional mode the document shall:
- 1) Provide the background and information needed to understand the system;
- 2) Provide the information needed to learn what can be done with the software and how to use it (for example, what goals it supports);
- 3) Provide examples to reinforce the learning process.
Information-oriented instructional documents provide the user with background or technical information needed to use the software properly. Examples of typical information-oriented instructional mode documents include: overview, theory of operation manual, and tutorial. Task-oriented instructional mode documents provide the user with procedures to achieve specific goals. Examples of task-oriented instructional mode documents include: diagnostic procedures manual, operations manual, and software installation manual. In the reference mode the document shall:
- 1) Organize and provide necessary information;
- 2) Facilitate random access to information.
Examples of typical reference mode documents include: command manual, error message manual, program calls manual, quick reference guide, software tools manual, and utilities manual.
In the following paragraphs the different types of on-line documentation will be analyzed more accurate. Here it is chosen to classify the various types into four categories: Messages, Helps, Reference material and Tutorials and CBT. Messages include those types of documentation that are initiated by the system. Helps are the systems that are accessed by the user when he or she needs information about a command. Reference material is the material that is accessed to get detailed information, for example about the syntax of a command of a programming language. And tutorials and CBT is on-line documentation that is used for teaching about the system it accompanies.
3.1 Messages
Messages are needed so that the user gets an idea about what went wrong, or about what the system or program is doing. With messages we mean system-initiated messages that occur when the user has performed an action. In the literature a number of different types of messages are found.
Shirk (1988) describes two sorts of messages, these are: system messages and error messages.
'System Messages: Information, instructions and problem indicators that can appear during the operation of software packages, including informationals (status and orientation information, prompts and menus) and warnings (alert and caution messages).'
'Error Messages: Information within software systems which indicates that a situation took place that threatens the integrity of the data, file, system or storage device, or that a given instruction cannot be executed. Included with the message that the specified problem exists can also be an explanation about why or how it occurred, where it occurred, the extent of the damage, and options available and methodology to recover from the situation and/or minimize the damage.'
Price (1984) distinguishes error messages as well.
'Error messages provide clear information to correct the error or back out trouble.'
Kearsley (1988) is talking in this framework about 'System-Initiated Helps'. He classifies this type of documentation as help, but because it is initiated by the system it is classified among the messages.
'System initiated messages are presented to the user as advice or suggestions. They are usually triggered by error conditions or other evidence that the user has a problem (missing parameters, repetition of exactly the same command, a long lapse of time before a response, out of range responses, and so on). Check messages (e.g., 'Are you sure you want to delete this file? Y/N') are a common form of system initiated help messages.'
Rubens and Krull (1988) add a new sort of system messages to the above mentioned, these are called are for support of interactive tasks. These system messages inform the user about the status of a process (e.g. the bar on the screen of indicating how far the computer is with copying a file (on the Apple Macintosh II)). They say that these sort of system messages are not the same as error and other system messages, because system or error messages do not help the user really, they just indicate that something has happened and do not give a solution.
3.2 Helps
As we talk about Helps we can ask the same question as about on-line documentation, 'Why is it needed'. Here for we find a number of reasons in the literature. According to Kearsley (1988) helps are needed for the following reasons:
- Helps provide an insurance policy against less-than-perfect design;
- As part of a safety net that catches people when they do something not anticipated in the system design;
- Helps contribute to the overall usability of a program by reducing the time it takes to complete an on-line transaction and the number of errors made.
An on-line help system was first not more than a few comments.
'On-line help began as a few comments added to show the user how to navigate, fill in the blanks, or execute a transaction.'(Price, 1988)
Later more sophisticated on-line help systems were developed, like dynamic helps, system-initiated helps (dealt with in the previous section) and help with multiple levels.
Some authors describe a help system as a system that gives a user assistance with the completion of a task. In 'On-line Help Systems, design and implementation' by Kearsley (1988) we find an accurate description of what a Help system is. Here we see that not only the content of the help-messages is important, but the way in which the user accesses the help system is important as well.
'A help system is one or more programs designed to provide user assistance embedded in a larger program or computer system. Although help programs are usually completely integrated with the application system they provide help with, the may also be separate and run concurrently with the system.'
'Help systems consist of two fundamental aspects: the interface and the content. The interface includes how the help messages are displayed, how the user accesses the help system, how the help system can be extended,..... . ...The content is what the help messages say. Both aspects are equally important.'
Shirk (1988) indicates that this assistance is build up out of directions. follows:
'HELP Facilities: Directions within software systems for solving problems the user may experience with software which resides within the system or software application it supports.'
According to Shneiderman (1987) describes the on-line help facility as a system existing out of keywords with accompanying descriptions.
'... the most common form of on-line help is the hierarchical presentation of keywords in the command language, akin to the index of a traditional manual. The user selects or types in a keyword and is presented with one or more screens of text about the commands.'
In the literature we also find that there are a lot of different kinds of help. Kearsly (1988) distinguishes the following sorts of helps:
Static versus dynamic helps: With static helps there are fixed entries that serve as an on-line glossary. With dynamic help on the other hand, the program determines the appropriate help message to display, based on the (last) action(s) of the user.
Next, helps can be distinguished on basis of the levels of help the program offers. The first level can be very general and as the users needs it he or she can request for more detailed help.
Houghton-Alico (1985) distinguishes helps in query-based helps and key-based helps. With the query-based helps the system can initiate the question, like 'Do you want additional information on how to do the merge-sort procedure, or the query can be initiated by the user, like 'Help Merge-sort'. The key-based helps are tied directly to a keyboard with a HELP or ? key, which the users press.
3.3 Reference material
Reference material varies from on-line user manuals to full text dumped on-line. Reference material is probably the most extensive form of on-line documentation and they are most of the time the same as the paper-based variant.
The following definitions on reference material do not concern just the on-line material, but as well paper-based reference material. According to Price (1984) reference material is:
'Material documenting every aspect of a program or computer hardware from the point of view of the user.'
Rubens and Krull (1988) on the other hand indicate that reference material is only concerned with the performance of a task:
'Often users need to discover how to perform a specific task. This usually occurs in situations where the task is unique or infrequent in the typical operation path.'
Price (1984) distinguishes as well the quick reference card, only as a paper-based document. Personally I think that there is an analogue of this quick reference card, for example the stencil accompanying WordPerfect that can be accessed by pressing two times the key F3.
'A summary of key information presented in tables and lists. Often designed to be pulled out of the manual and placed on the keyboard.'
The on-line user manual is a real type of on-line documentation, but the way Shneiderman (1987) describes it makes it look like a paper-based product 'dumped' on line.
'... an electronic version of the traditional user manual. The simple conversion to electronic form may make the text more readily available but more difficult to read and absorb.'
This is more or less the same than the full text described by Rubens and Krull (1988). Full text is duplicated printed text, dumped on-line.
Finally, Shirk (1988) provides us with a description of on-line reference guides. On-line Reference Guides: Comprehensive, detailed compilations of information about software or hardware that are structured like dictionaries or encyclopedias and accessed through various indexing schemes. They are organized for quick access by users who are knowledgeable about the basics of their subject matter.
3.4 Tutorials and CBT
The last category that is mentioned here is the category of Tutorials and CBT. These two are probably part of a recent development to make use of the computer as a teaching medium.
Shirk (1988) makes a distinction between software and hardware tutorials and CBT. The difference between these two is that CBT can deal with other aspects than the software and hardware tutorials. For example, the CBT can deal with background information that is not necessary to operate the software or the computer system. She defines this as follows:
Software and Hardware Tutorials: On-line sets of instructions consisting of step by step procedural information and amply illustrated with examples and graphics. They are designed for first-time (or beginning-level) users, and they may be either without user interaction or with user interaction in which the system gives feedback about the user's performance.
Computer-Based Training (CBT): Instruction on any subject-matter which is delivered by a computer. It is not necessarily limited to tutorials about software and hardware, and it may include other media such as audio tapes and video-discs. In its general sense, CBT includes all forms of the use of computers in the support of learning. It has been defined as 'any time a person and a computer come together and one of them learns something'. Although there are numerous synonyms for CBT, this term (like 'on-line') is becoming standard through common usage.
Shneiderman (1987) describes what an on-line tutorial does
'This potentially appealing and innovative approach uses the electronic medium to teach the novice user by showing simulations of the working system, by attractive animations and by interactive sessions that engage the user.'
Rubens and Krull (1988) indicate why on-line tutorials are being used.
'Corporations often depend on on-line tutorials. They have elected this media because it reinforces the integrated 'feel' of products and introduces the new user to the product in the environment in which the actual product will operate.'
Tutorial documentation (Crandall, 1987) is a more embracing concept than on-line tutorials and it embraces as well paper-based tutorials.
'Tutorial documentation can be contrasted with other types of computer documentation by its educational intent - unlike reference, installation, or maintenance manuals, the purpose of tutorial documentation is to teach. The underlying assumption of tutorial documentation is that it will teach the learner (user) the basic skills needed to use a computer related product.'
Further Crandall (1987) states that tutorial documentation must stand alone, so that the user can depend entirely on the tutorial for the instruction needed. Last she indicates that a tutorial document must contain a number of 'tools', like a table of contents, a glossary, and an index.
A final type, and a rather awkward, perhaps out of place, type is the canned demonstration (Rubens & Krull, 1988):
'Showing people how programmes operate and look like.'
A canned demonstration is build in the software program it supplies information about. It can be a picture-slide show, an example or an animation of the program. Important is that it shows the possibilities of the program.
4. Types of audiences
To determine what type of on-line documentation is needed it is important to identify the audience. In the literature some groups are distinguished. Schneider (1982) handles a so called 'user sophistication taxonomy'. In this taxonomy he distinguishes 5 types of software users:
1. The Parrot
An individual at the lowest level in the taxonomy, the Parrot, has minimal knowledge of the computer system. The Parrot operates with the smallest chunk available: a single character. A user at this level approaches the computer system and types strings of characters. This individual does not think, question understand or synthesize the text entered.
2. The Novice
Unlike the Parrot, the Novice analyzes each item, thus extracting lexical information. The language components now have meaning and can be used in a flexible manner.
3. The Intermediate
The Intermediate operates with items in fields and with fields in statements. The Intermediate begins to concentrate on the task rather than its components. Use of full language may be restricted by a lack of knowledge. Thus, the Intermediate continues to expand significant effort on language details. Towards the end of the intermediate level, considerable skill in the understanding and manipulation of a segment of the command set has been achieved.
4. The Expert
The Expert realizes that an interconnected collection of statements can be more productive for certain tasks. The Expert uses the largest chunk: a program or procedure. An Expert thinks about the possible outcomes of commands and has the ability to take appropriate action.
5. The Master
The Master expands the existing system, creating new objects and facilities to solve new problems whose solution cannot be derived from existing functions or objects within the system. Unlike the lower four levels, the chunk size is not a determining factor.
Horton (1990) distinguishes only four types of users. The first one he mentions is the novice user. The second type is the occasional user, which can be compared with the intermittent Brockmann (1990) mentions. The third type is the transfer user, who is not a user yet, but uses a different system. The forth type Horton distinguishes is the expert user.
Brockmann (1990) distinguishes six types of users. The first four, the parrot, the novice, the intermediate, and the expert match the description of Schneider (1982) for these four. The fifth type, the transfer user is equal to the transfer user Horton (1990) describes. The sixth type is the intermittent user. The intermittent users:
'..work with the software so infrequently that they do not go through the learning stages. In fact, they may not want to go through the learning stages.'
Brockmann (1990) makes another distinction between users, based on their preference for a certain medium. We are not dealing with this, because here it is about on-line documentation.
So, overall the following seven types of users are mentioned in the literature:
- 1. the parrot
- 2. the novice
- 3. the intermediate
- 4. the expert
- 5. the master
- 6. the intermittent
- 7. the transfer user
5. On-line documentation in connection with the audience
It is obvious that the indicated types of audience or users need different types of on-line documentation.
Horton (1990) first starts with identifying what information the user needs. The novice needs information about how to operate the program and/or the computer. The types of documents that are best suitable for this are tutorials and helps. The occasional or intermittent user needs reminders of details, by messages, menus or help, and he needs information about how to do new tasks, by means of tutorials. The transfer user needs information about the differences between products and this can be given by tutorials, messages, menus and help. The expert needs information about advanced features, by on-line reference manuals, and he needs information about shortcuts, this information is stored in the help system.
According to Foehr and Cross (1986) needs a novice user great detail, and as the user becomes more experienced less guiding is required. For an experienced user a quick reference suffices.
Brockmann (1990) indicates that tutorial documentation is used for the first month a user is working with the software, and after the first month he can use reference documentation. Brockmann sophisticates this raw bipartition in the following way.
The parrot needs a task-oriented guide that gives him quickly sense of success and he has to practice immediately on practical projects. The novice needs a task-oriented tutorial with in it a visualization of the whole product or system. The novice needs to practice a lot. The intermediate needs a reference manual with visualization in it, and he needs to practice as well. The expert needs a quick reference card. The intermittent needs a very robust help system, that is rather intelligent.
So, it is clear that different users need different documents with different content. In the next chapter a classification is presented in which the type of documentation is connected with the type of user.
6. On-line software user documentation
In the previous chapters is dealt with a number of aspects of on-line software user documentation. In this chapter it is the intention to synthesize the gathered information, so that the question 'What is on-line software user documentation?' is answered. The answer on this question will not be a definition a description of what I think that 'on-line software user documentation' is, based on what is found in the literature. Next to that a classification will be presented in which is indicated what type of user needs what type of on-line documentation.
6.1 A description of 'on-line software user documentation'
When we talk about on-line software user documentation, we are dealing with three aspects. The first aspect is on-line documentation. In chapter 2 we have dealt with on-line documentation. The second aspect embraces the different types of on-line documentation. Attention to this has been paid in chapter 3. The third aspect is the software user. In chapter 4 it is indicated that there are different types of users with different kinds of needs. On the ground of these three aspects a description of on-line software user documentation can be formulated.
From the information gathered about on-line documentation we can infer that:
On-line documentation is information stored in the computer and written specifically for access only be means of a computer terminal.
From the information about the different types of on-line documentation we can infer:
On-line documentation ranges from simple messages to complicated tutorials and CBT.
From the information about the different types of users we can infer:
The software user needs, depending on his experience and needs, different types of on-line documentation.
After mixing these three components the next description of on-line software user documentation comes into existence:
'On-line software user documentation is information accompanying software that facilitates working with the software and that enables the user to learn how to work with the software. This information is stored in the computer and written specifically for access only by means of a computer terminal. This information may be build into the software program, or it is stored and organized in separate programs that can run concurrently with the software. The information should be developed for the different user groups, like parrots, novices, intermediates, experts, masters, intermittents and transfer users.'
According to this definition all the classes that are mentioned in paragraph 3.1 to 3.4 are covered. Messages are normally build in the software, just like help systems most of the time are. Other help systems are separate programs, just like the on-line reference materials and the tutorials and the Computer Based Training.
6.2 Software users and the on-line documentation they need
Now that is indicated what on-line software user documentation is, and what different types there are, and what different users there are, it is possible to classify the different types according to the needs of the software users. In figure 2 it is indicated what users need what type of documentation. It has to be noticed that from the four categories mentioned in chapter 3 sometimes more than one type is represented in figure 2. This has been done because otherwise the differences between the needs of the different users are not clear.
According to the literature a parrot needs a task-oriented guide and he has to practice immediately. System-initiated help gives him this chance. If he is making mistakes, the system-initiated help will support the parrot while doing so. The tutorial here is added, because an adjusted tutorial, that allows the parrot to exercise immediately would fit his special circumstances as well. System messages or error messages are not appropriate here because the parrot will not understand what they mean.
Figure 2: Software users and the on-line documentation they need
The novice needs, according to the literature, the same types of on-line documentation, and next to that normal help can be provided. System and error messages are not required because the novice will not understand them and this is already partly covered by the system-initiated help. Reference material is too detailed at the moment, although Foehr and Cross (1986) recommend great detail for the novice user. Perhaps when the user is starting to become more experienced this is required, but not when he just starts working with the software.
The intermediate does not need the system-initiated help anymore. With the help of reference guides he can interpret the system and error messages. The availability of a tutorial is still recommended, but now more for guidance during practicing. The help system is still needed.
The expert makes use of an on-line quick reference card, just for reminders. The expert knows what the error and system messages mean and the help system will probably only used for quick reminders.
The master only needs the system and error messages. The quick reference card is not required but a practical tool for quick reminders.
The intermittent needs like the novice system-initiated help, normal help and a tutorial. The tutorial has to be short, because the intermittent has not got much time for learning the basic skills required to work with the software. Probably the best tutorial for this type of user is a brief general description of the software, followed by a part in which the intermittent can choose certain units of interest.
For the transfer user the documentation has two objectives. First it has to be shown what the software can do and how it looks like. Here for the canned demonstration is ideal. For working with the software the transfer user needs help, either system-initiated or normal help. Because he has worked before with a system like the one he is going to work with the system and error messages are appropriate.
7. The future
In this final chapter some possible future developments of on-line software user documentation will be presented. These developments are based on what the various authors predict. There are three main developments. The first is that the development of on-line software user documentation and the development of the software will take place at the same time. The second development is using hypertext technology for the development of on-line software user documentation. The third development concerns the storage of the on-line software user documentation.
7.1 Concurrent development of software and the on-line documentation
The production of on-line documentation accompanying the software, that is manuals and instructional programs, and the software development will all become part of the same process (Shirk, 1988). Grice (1988) describes this as follows:
'The information-development process must be considered in the context of an overall product-development process; information developers are part of the product development team in the same way as hardware developers (engineers) and software developers (programmers).'
It is important that this happens, because at the present time most of the documentation belonging to the software is written afterwards. It is more a bad boring job that is done after the software is completed, and most of the time the documentation is of poor quality.
7.2 Using HyperText technology
Carlson (1988) predicts that hypertext will take an important role in future, and even in present, on-line documentation systems development. She describes this as follows:
'Hypertext as the backbone for an on-line documentation system permits advanced design features - such as enhanced functionality, customized views, and improved knowledge synthesis and representation - which, in turn, increase the user's ability to interact productively with information.'
Horton (1990) provides us with a number of advantages and disadvantages of hypertext as on-line software user documentation. Next to that he indicates where hypertext eventually could be used. The advantages of hypertext are:
- non-linear organizations are easy in hypertext;
- hypertext models information in associative webs reminiscent of the semantic networks of human memory;
- users have more paths to information;
- multiple organizations are possible;
- hypertext promotes collaboration (multiple authors combine and organize their thoughts).
The disadvantages according to Horton are:
- information is hard to find;
- users get lost in hyperspace;
- reading sequences are unpredictable;
- hypertext are difficult to create and maintain;
- systems are not permanent.
Next Horton provides us with a number of situations in which hypertext can be used. It is open whether or not these situation are specifically applicable to on-line user software documentation. The situation that Horton mentions are:
- to teach concepts;
- for highly annotated documents;
- for problem solving systems;
- for loose collections of interrelated documents;
- to model and teach organization.
7.3 CD-ROM as storage medium
In the future on-line documentation, either for the software user or for other goals, probably will get larger. Brockmann (1990) predicts this because of two reasons. First, with the help of large-scale digital storage means like CD-ROM, data can be distributed more cheaply than on paper. Second, the demand for for customized and accurate user documentation of software products grows continues. The large storage capacity and the small package of the CD-ROM are the advantages that will take care that a lot of documentation is going to be put on this data carrier (Rubens & Krull, 1985; Brockmann, 1990).
The use of CD-ROM for storing data has its consequences as well. Wilson (1985) indicates that:
'To make effective use of CD-ROM the publisher will have to acquire new skills in structuring his information for loading onto CD-ROM and for interaction use with the associated software.'
Wilson (1985) and Turner (1985) as well see manuals and instructional programs as part of the main application areas of CD-ROM. Horton (1990) expects that all documents finally will go on-line and computers will grow more like books. He does not indicate if the storage medium is going to be the CD-ROM. Houghton-Alico (1985) is as well convinced that most of the on-line software user documentation will go on-line, but nevertheless paper-based documentation will not disappear:
'The importance of this type of documentation (on-line interactive documentation) will increase, and hard-copy documentation gradually will assume the role of supplemental information, such as initial access instructions and quick reference material.
8. Discussion
In this literature review an answer on the question: 'What precisely is on-line software user documentation?', has been found. To find an all-embracing answer it was first indicated what on-line documentation is, next the different types of on-line documentation were analyzed, and finally the different types of user were indicated.
This has lead to a precise description of what on-line software user documentation is and a classification in which it is determined what types of on-line software user documentation are suitable for what type of user.
Further some attention has been paid to future developments, which are perhaps already taking place. These developments, indicated in the previous chapter, do need some further analysis.
Finally it seems that certain advantages of on-line documentation are at the same time disadvantages. It would be interesting to know if these advantage or of greater importance
Bibliography
Brockmann, R.J. Writing Better Computer User Documentation, form Paper to Hypertext. New York: John Willey & Sons, 1990.
Carlson, P.A. 'Hypertext: A Way of Incorporating User Feedback into On-line Documentation'. In: Text, ConText and HyperText : Writing with and for the Computer. Cambridge, MA: The MIT Press, 1988, pp. 93-110.
Cohen, G. & Cunningham, D.H. Creating Technical Manuals. New York: McGraw-Hill, 1984.
Crandall, J.A. How to write tutorial documentation. Englewood Cliffs, New Jersey: Prentice-Hall, 1987
Foehr, T. & Cross, T. B. The soft side of software. New York: John Wiley & Sons, 1986.
Grice, R. A. 'Information Development Is Part of Product Development - Not an Afterthought'. In: Text, ConText and HyperText : Writing with and for the Computer. Cambridge, MA: The MIT Press, 1988, pp. 133-148.
Horton, W. K. Designing and Writing On-line Documentation, HelpFiles to Hypertext. New York: John Willey & Sons, 1990.
Houghton-Alico, D. Creating Computer Software User Guides. New York: McGraw-Hill, 1985.
IEEE Standard for Software User Documentation. Institute of Electrical and Electronics Engineers, Inc. New York, 1988.
Kearsley, G. On-line Help Systems, design and implementation. Norwood, New Jersey: Ablex Publishing Corporation, 1988.
Min, F.B.M. 'Parallel Instruction: a Theory for Educational Computer Simulation'. In: Interactive Learning International, 8 (1992) no. 3, p177-183.
Price, J. How to write a computer manual. California: The Benjamin/Cummings Publishing Company, 1984.
Price, J. 'Creating a Style for On-line Help.' In: Text, ConText and HyperText : Writing with and for the Computer. Cambridge, MA: The MIT Press, 1988, pp. 329-342.
Rubens, P. & Krull, R. 'Designing On-line Information'. In: Text, ConText and HyperText : Writing with and for the Computer. Cambridge, MA: The MIT Press, 1988, pp. 291-310.
Schneider, M.L. 'Models for The Design Of Static Software User Assistance.' In: Directions in Human/Computer Interaction. Norwood, NJ: Ablex, 1982, pp 137-148.
Shirk, H. Nickels. 'Technical Writers as Computer Scientists:The Challenges of On-line Documentation.' In: Text, ConText and HyperText : Writing with and for the Computer. Cambridge, MA: The MIT Press, 1988, pp. 311-327.
Shneiderman, B. Designing the User Interface: Strategies for effective Human-Computer Interaction. Reading, MA: Addison-Wesley, 1987.
Turner, S. 'CDROM - here 's the solution, now what 's the problem?' In: Electronic Publishing, Corporate and Commercial Publishing. International Conference Proceedings. Londen, 1985, pp. 123-128.
Wilson, W. 'Implication of CDROM for electronic publishers.' In: Electronic Publishing, Corporate and Commercial Publishing. International Conference Proceedings. Londen, 1985, pp. 129-136.
