Creating effective hypercard online documentation and training
Authors: M. Natchez, T. Prose
Venue: Proceedings of the 7th annual international conference on Systems documentation (1989)

In recent years, the &ldquo;hypers&rdquo; have made a strong impact on technical communication. Hypertext and hypermedia applications have shown that it is possible to communicate information in user-defined, non-linear ways, taking advantage of multiple sources and delivery mechanisms. HyperCard is a particular application, written by Bill Atkinson and packaged with every Macintosh computer, that provides a structure for creating an easy-to-use, interactive learning experience that can easily combine text, graphics, sound, animation, and even video-taped segments. Depending on the design of the application, users can proceed sequentially along a predefined path, or jump between topics of interest. For example, rather than giving a student a manual that starts at page one and goes sequentially through the range of material, the instructor or technical writer gathers relevant material, enters it on-line, and provides indexes or menus for students to direct their own learning. Material may be graphic, audio, text-based, animated, interactive, or any combination of the above. This creates a tremendous variety in the learning system and lets the user determine the most relevant path through it. With the advent of this type of application, however, writers, trainers, and program developers face new problems in design. These problems include envisioning the overall design of the application, designing effective mapping techniques, streamlining text, creating consistent screens and metaphors, creating guideposts for the user, and planning the effective use of sound, animation, and graphics. This paper addresses these problems and offers guidelines and solutions. We will cover strategies for planning and development of HyperCard projects, and explore two case studies: one, turning a brochure into a HyperCard presentation; the other, designing a HyperCard troubleshooting guide for mainframe operations. While the examples used focus on HyperCard, the instructional design precepts behind them are applicable to any hypermedia presentation. In the flash and dazzle of the new technology it is important to integrate basic writing and instructional design theory. These are all the more critical because they are often neglected. Right now, when technology is changing so rapidly, we tend to be seduced by the newest and most exciting video laser displays, touch screen presentations, and animated screens, and forget that a poorly designed or executed presentation is equally ineffective in whatever medium it is presented. The first step for any project, HyperCard or not, is to perform a needs assessment. If you are unfamiliar with this term, a needs assessment is the determination of who your audience is and what they need. To perform the assessment, you interview the people who know, you interview the people who are going to need to know, and you determine the best way to get the information from one to the other. Identifying your audience and what they need to learn is the first step in any instructional design, and there are several excellent references on this process listed in the bibliography. Next, you must determine whether a specific project will translate effectively into a HyperCard application. The material that works best in HyperCard is subject matter that can be broken down into fairly discrete segments. On-screen reading does not work for long pages of text, so you have be able to convey meaning in a few paragraphs or less. Can this information be assembled in a series of paragraphs that can be linked together by a road map? If so, HyperCard is a viable alternative. Some examples of information that translates well are troubleshooting procedures, brochures, advertising material, orientations, maps, and job aides. The subject can be large &mdash; even encyclopedic &mdash; as long as it can be broken down into manageable subject areas. Job aids translate well to HyperCard because typically, you are dealing with particular job functions that you can document and show on-screen in a lively and engaging way. You can convey the information before the user gives up on reading the screen. Marketing presentations can translate into powerful hypermedia presentations, because you are trying to present the features of a product or a service in an eye-catching way. These images can be conveyed more easily with pictures, sound, music, and short bursts of text than they can be on a one-dimensional page that someone is likely to throw into the trash. We have worked on projects to translate reference manuals into HyperCard. These can translate effectively because the essential focus of a reference manual is: first, find the information you need; and second, describe it as briefly as application can be implemented here, as long as text is kept to a maximum of three screens per topic. The reader is not interested in the entire reference manual, but rather in one specific piece of information at a time, and then perhaps related subjects. Another type of presentation that translates well is one that requires the user to move in a more structured way with alternate paths. For example, in troubleshooting you have to go from step one to step two to step x, with the progression depending on the problems encountered and the previous response. It is easy to miss a procedure on a page, or to get confused as to the next step. By putting the troubleshooting into a HyperCard application, where you can click and change from step one to step two, you encourage the user to focus on each section of the presentation separately. You also have a natural decision-based branching mechanism. These enhance the presentation. Projects that do not lend themselves to HyperCard presentation include most scientific articles, theoretical discussions, and abstract concepts. These do not work in the kind of &ldquo;burst of information&rdquo; environment that HyperCard provides. Translating an ordinary book to HyperCard generally is not a good idea. Philosophy, detailed technical information, or novels are not natural projects for HyperCard. Once you have determined that a project will benefit from presentation in HyperCard, you should turn your attention to mapping the project and determining how the user is going to access the information. This is the problem of providing structure so that the user does not get lost. You need to keep the structure flexible, but you also need to make your information accessible sequentially when appropriate. It is important to keep in mind that there are many types of learners. The application must be available not only to independent thinking, creative people, but also to those of us who like to go through learning processes in a more structured and orderly fashion. Mapping the application is the first job. It requires a clear overview of your objectives, how you envision the user interacting with your material, and what the nature of the logical links between subjects. The more thorough the mapping process, the more satisfactory the end result. It is here that basic instructional design rules can help. Define your objectives and your methodology. Then map your material in as simple and straightforward a manner as possible. Any &ldquo;flash&rdquo; comes later, when you enhance the presentation. Figure 1 shows a sample HyperCard application map. The map shows how the user will access various topics covered in the application. In the example shown, the application includes basic operations troubleshooting procedures and background information on the computer system. There is a startup screen, with an optional introduction to the Macintosh. Then the Main Menu appears. From there, users can select individual topics, returning to the menu at the completion of a topic, or go to an index/glossary, for a definition of a term or concept. They can move to a related procedure, or see how a component fits into the system configuration when appropriate. Access to specific procedures is also available by looking up an error message or symptom or by looking at a map of the system, selecting a component. Users are then directed to the related procedure. This allows access by concept, by error message, by symptom, by visual overview, or by procedure. In addition to this initial map for developing the application, you must also build in maps and guideposts to help users navigate easily to the information they want. These range from the simple (forward and backward arrows, a return symbol to return to the starting menu) to the more complex (specific icons, imbedded maps, menu bars, webbed views). They are all designed to help users determine their current position and where to go next. For example, you might place a &ldquo;where am I&rdquo; button in the lower right hand corner of the screen. When users click this button they can get an overview of where they have come from, and where they can go. You can go up or down several levels by clicking further. This is a very effective mapping technique. Another technique is to provide a consistent menu bar that gives simple choices such as: go back one, back to start (start meaning point of entry), and index. An sample of this type of menu bar and index is shown in figure 2: Bookmarks are another excellent technique for helping the users find their way around. A bookmark is a way users can say, &ldquo;save my place, go to somewhere else, and then return.&rdquo; A web view of the application is also very helpful. A web view is an asymmetrical picture or web of related topics and where they might lead. It gives the user a feel for how the current text is linked to other topics in the application. Another proven navigation tool is a browser. This is a map of the hard links that you have created so the user can quickly see where the logical connectors are going. The browser enables users to see the direction you had in mind in the design of the application. They can then choose whether or not to follow that path. A filter is a more sophisticated mapping tool. With a filter, users can set conditions or choose conditions from a list, and then view a display of topics that correspond to these criteria. This creates a subset of topics from the data base of available material. Indexes are still an excellent way to find information. Many of on-line help systems use them for that reason and they're also effective for HyperCard. Whatever techniques you choose, well-designed navigation for the user is of critical importance to the success of the application. When you have chosen your approach, you must then map a logical flow from several perspectives. You have to create hard links so that the user who doesn't want to explore without a guide can explore the application in a guided fashion. Specific icons to represent topics or areas are also helpful. For example, in a complex procedure with a section on loading tape drives, on CPU commands, and on disc commands, you might have a representative icon for tapes, CPUs and discs. When users are in the CPU procedure, they could click on the tape icon to return to the tape drive procedure, or on the disc icon to go to a procedure for disc drives. The idea of icons brings us to the question of metaphor in general. In selecting images for icons, graphic illustrations, or concepts, it is important to keep imagery simple, logical, and consistent. At the simplest level, if you decide to use forward and backward arrows, they should always be the same arrows, in the same area of the screen. The appropriate icons should be identified and maintained throughout the application, and they should work in a logical way, a way that makes intuitive sense. For example, if you have chosen the image of a VCR control panel as a navigation tool, then the buttons should function in the same way as a real VCR. Consistency is also important in the layout of the screen&hellip;Consistent screen design provides a high comfort level for the user. This does not mean that you should only have one screen pattern for every display, but you might have five or six basic patterns and then add to these, repeat them, vary them, add animation, add sound, change, fade, scroll, etc. However you enhance them, the basic patterns, like the road maps, provide a framework for the user. You should try to have a consistent area for instruction, for feedback, and for navigation, so users always know where to look for specific information. The design of the screen is also very important. It is not possible to cover all the principles of screen design in this presentation; screen design is a field in itself. But there are some basics to keep in mind. First, you should have plenty of white space on your screen, never less than 20% is the rule for the page, never less than 30% is a good rule for on-screen presentations. This helps the user focus on the text. Another basic rule is to use both upper and lower case letters for text; the eye can easily distinguish patterns in letters that are upper and lower case. Use all capitals only for emphasis. X-height of fonts is also important. X-height is the distance from the bottom of a letter to the top of the lower case letter. A font with a low x-height, like Times, is harder to read on-screen than a font with a tall x-height, like Stuttgart. In general, use fonts between 12 and 18 points for best onscreen readability - occasionally larger for titles or, very rarely, smaller for notes. Let's look at several screen examples to illustrate some effective designs. (Screen examples will be shown and discussed here.) Writing style for HyperCard is another important area. Technical writing can be oppressively convoluted and scholarly. This is something you must avoid in HyperCard presentations. Writing for HyperCard must be clear, direct, and pared down. It needs to have a punch to it &mdash; active voice, imperative verbs, short sentences, and very specific words. Especially for HyperCard, good writing is clear writing. You should be able to understand the words as quickly as your eye can read them, and text should convey information in as few words as possible. For example, you could change, &ldquo;You should try to avoid using long, involuted sentences in your presentation&rdquo; to &ldquo;use short, clear sentences in your presentation.&rdquo; When possible, use the font and style capabilities of the Macintosh to pare down your sentences. For example, instead of &ldquo;If you want to choose open from the file menu, move to the file menu, pull it down, and choose open.&rdquo; You might write, &ldquo;To open a file, from the File menu, select Open.&rdquo; This makes use of fonts to clarify your point and uses about half the number of words. Use plenty of examples - graphic examples where possible. HyperCard lends itself to visual presentations, so exploit this capability. If you can say it in a picture, don't say it with words. Good graphics greatly enhance HyperCard. Any place where a picture will convey an idea, you can use a picture to enhance the text. You can use libraries of existing graphics or scan in custom or existing graphics. The final area we will discuss is the inclusion of animation and sound. The first rule here is &ldquo;less is better.&rdquo; Cuteness or pizzazz, which are the basic functions of animation and sound, are wonderful enhancements to presentations. However, they are wearing as a steady diet. There are two very effective ways you can this technique in your presentations. One is to illustrate how to perform an activity. You can use an animated presentation: move to this, press this, and this happens. Another way is to use an animated display for entertainment, to add a little whimsicality to the presentation. You may have seen the demo of a camera with various shutter speeds taking photos with different exposures. This makes a point in a charming way with animation, and is very effective in small doses. In the same way, sound can capture the ear, focus the user, simulate an event, or provide a background. If you are using background music, it should be unobtrusive, and in line with the tone of your presentation. I would never recommend that you use music as a background for an entire presentation, but only for portions. For example, in one of the case studies we are going to look at, we had an automated tour of several topics. During the automated presentation we used a musical background. If you decided not to take what we called the &ldquo;guided tour,&rdquo;but to find your way through the presentation yourself, there was no music. The music was there to keep you engaged while things were happening on the screen. With that, we will review the case studies, and talk a little about them. We will use our checklists to evaluate the presentations and their success or lack of success, and learn from the presentations themselves.* In conclusion, I want to summarize the points we have discussed here. We opened this presentation with overall management concerns. We presented guidelines for projects to determine which should or should not be attempted in the HyperCard environment. Once we determined that a project would benefit from presentation in HyperCard, we discussed the steps necessary to plan for and organize the development of this application. We discussed mapping techniques, and methods to keep the user from getting lost or feeling overwhelmed by this new environment and strategies for helping the user navigate through an application. We discussed how to build these keys into the original application design. We discussed the importance of consistency for icons, metaphors, and screen layout, and discussed basic criteria for good screen design. We also explored HyperCard writing techniques, focusing on how to pare the writing down to the minimum necessary to convey meaning. We discussed how to present text in ways that make it memorable in a screen environment, as opposed to designing for the page. Finally, we discussed the use of sound, animation, and graphics, and how these can be used to accent a presentation. We demonstrated two case studies, evaluated them according to a checklist, and discussed user reactions to the case studies, and what was learned from user feedback. Our belief is that thoughtful selection and planning can lead to excellent HyperCard applications.