| Teaching User Documentation by Modular Decomposition | | BIBA | PDF | 1-2 | |
| John R. Talburt; W. Steve Anderson | |||
| Documentation design through stepwise refinement into two-page modules is
certainly not new. An early approach to structured documentation called STOP:
Sequential Thematic Organization of Publications was used in the early 1960's
(Tracey, Rugh, Starkey [4]). Most recently, Edmond Weiss has very eloquently
and succinctly described the modular approach to documentation in his book, How
to Write Usable User Documentation (Weiss[5]).
The focus of this workshop concerns the use of structured methods in teaching user documentation. Our experiences in academia (Anderson, Talburt [2]) have shown modular decomposition to be an effective instructional approach, particularly for computer science and engineering students, an audience already familiar with structured design concepts. Students with technical writing backgrounds have also found modular decomposition to be a useful alternative method for manual prototyping. | |||
| Helping the User Retrieve Data from a CD-ROM | | BIBA | PDF | 3-4 | |
| Susan Feinberg | |||
| This abstract provides a brief history of the development of the product and an overview of the kinds of interfaces that helped users retrieve data from the CD-ROM. A beta-test provided the information that the development team used to design and improve the user interfaces. | |||
| An Experiment in Teaching Online Searching to College Students | | BIBA | PDF | 5-11 | |
| Eva M. Thury | |||
| Today's electronic retrieval systems were designed for information professionals like reference librarians or database search specialists or for those who want to emulate the behavior of such professionals. That is, online databases are oriented towards searchers who are typically working to locate information for others, on topics they are not themselves studying (Marchionini and Shneiderman, p. 71). The documentation for online retrieval systems is accordingly intended to help users maximize the measures of successful information use appropriate to information professionals, the measures formulated by information science: precision and recall. Yet, as online information systems become more accessible, there are more groups being trained to use them without intermediaries, at various levels of competence. This can include students at any level from gradeschool to college, as well as technical and business users who have been taught to use online search systems for themselves. This is a growing population (Borgman, p. 49) of end users gathering information for themselves. The increasing presence of users who do not fit the model of the information professional suggests that there is a need to reconsider the orientation and aims of documentation for online sources in the light of what is becoming understood about the differences between the behavior of these two groups of users. | |||
| OLH: An On-Line Help Facility for Managing Multiple Document Types in their Native Formats in a Distributed Environment | | BIBA | PDF | 12-20 | |
| Kevin M. Cunningham | |||
| In trying to construct and maintain a useful and comprehensive on-line help
system that organizes all the material available in a heterogeneous distributed
UNIX-based environment, our documentation group encountered three fundamental
difficulties in dealing with existing online documents:
* an incompatible variety of formats
* no central location
* political constraints
Rather than spend our time converting and relocating perfectly good existing
documents, we developed a menu-based help browser, OLH, that allows us to
maintain the documents in their native formats and in their original locations
in a way transparent to the user. The OLH system:
* makes all our online documents accessible through a common interface
* supports on-the-fly conversion of some document types to support users who
can't view the documents in their native formats (e.g., over dialup) * allows us to maintain the hardcopy and on-line versions of many documents in single-source modules OLH is built on an operating-system-independent database, and currently has interfaces for devices supporting the X Windows System and plain-text terminals. | |||
| Online Help in the Real World | | BIBA | PDF | 21-29 | |
| Susan D. Goodall | |||
| Today online documentation is a required part of any PC application and in
the future online documentation will replace most of the manuals that currently
accompany software applications.
Online documentation can take many forms. However, when people talk about online documentation, they are usually talking about online help. Online help is accessed from within the application, teaches the user how to use an application, and provides answers to the user's questions. This paper describes one successful approach to creating online help for a complex application that runs under Microsoft Windows 3.0. | |||
| INFO: A Simple Documentation Annotation Facility | | BIBAK | PDF | 30-36 | |
| Scott Tilley; Hausi Muller | |||
| INFO is a simple hypertext facility that can be used to annotate standard
documents (such as source code) in an unobtrusive fashion. Experience with
INFO has shown that programmers tend to provide more detailed design and
implementation decisions if they have more than a few lines in which to do so,
and are allowed to document these in a free-format fashion. INFO is not meant
to be the ultimate hypertext system. Rather, it can be used in conjunction
with standard tools under IBM's VM/CMS to provide a simple yet efficient
document annotation facility. Keywords: Annotation, Documentation, Hypertext, Maintenance, Software | |||
| Preparing for the Inevitable: Localizing Computer Documentation | | BIBA | PDF | 37-43 | |
| Nancy Hoft | |||
| In the past two years alone, global change has been dramatic, exciting, and
telling for American business. The future won't be any less boring. In 1992,
the European Economic Community (EEC) becomes a strong international economic
force. The year 1997 probably will mark the introduction of yet another
strong, international economic force, China. And in our own hemisphere,
President Bush is pushing hard and fast for a North American Trade Agreement
among the US, Canada, and Mexico. All of this spells increased competition for
American businesses and, for us, technical communicators it means start
preparing NOW to address a diversity of international audiences.
International business specialists use the word "localization" to describe communicating in local terms to a locale. A locale is the linguistic, cultural, and legal characteristics of a nationality, ethnic group, company, or individual. It can be as big as a continent, or as small as a user. As communication specialists, are we prepared to address the inevitable localization of the products we write about and, consequently, the documentation we write? This paper compiles the results of interviews with professionals from seven companies in the computer industry who manage their companies's international efforts. All interviews focused on each company's localization process. What do they do to localize their documentation? How effective is it? Can they test and control its effectiveness? Is it costly? What are some typical roadblocks and how have they overcome them? Is it possible to write in English to minimize translation errors? Each company's localization process is discussed separately. | |||
| SUPER: Documentation and Training | | BIBA | PDF | 44-48 | |
| Ivan Maffezzini; Sylvie Dumas; Bernard Weber | |||
| This paper is a case study of the integration into an engineering project of on-line documentation based on hypertext. We will start by describing briefly the system and method of development before the introduction of hypertext, and then outline the changes effected by its introduction. The principal exchanges between the developers of person/machine interface (PMI) will also be described. An example of the influence of hypertext on system definition will be presented. Finally, we will sketch out predicted improvements. | |||
| Procedure Writing Across Domains: Nuclear Power Plant Procedures and Computer Documentation | | BIBA | PDF | 49-58 | |
| Douglas R. Wieringa; David K. Farkas | |||
| Computer documentation, and in particular documentation for end-user
software applications, is so prevalent today that it is easy to forget the
larger world of procedure writing, of which computer documentation is only a
part. Numerous types of procedures exist, ranging from administrative
procedures that focus on human activities, to procedures for assembling
consumer products, to procedures governing the operation, maintenance, and
repair of complex industrial equipment. One domain in which procedures play an
important role is the large and complex process-control facilities such as oil
refineries and chemical plants. This paper discusses procedures and procedure
writing at one kind of process-control facility -- the nuclear power plant. We
think that the differences between nuclear power plant documentation and the
documentation of computer systems -- especially software applications -- are
interesting and instructive, and we will try to point out some lessons learned
from procedure writing in the nuclear power industry that apply directly to
software documentation.
We first provide an overview of recent efforts to improve procedure quality at nuclear power plants and discuss some of the distinctive challenges faced in documenting nuclear power plant procedures. We then describe how some of the techniques used by nuclear power plant procedure writers can be applied to software documentation. We cover the process of developing and testing nuclear power plant procedures and two of the formats that have proven valuable in creating usable plant documentation. The first is a two-column text format in which users can select either general or highly detailed instruction. The second is a flowchart format that reduces the user's cognitive burdens in following highly branching procedures. The paper concludes with comments on the potential of online procedures, an area in which the nuclear power industry could learn from the writers of computer documentation. | |||
| Important Issues in Hypertext Documentation Usability | | BIBA | PDF | 59-66 | |
| Flerence M. Fillion; Craig D. B. Boyle | |||
| In 1987, Conklin [1] wrote about the excitement created by the Hypertext
concept. Since then, many papers have been published on the subject, and many
empirical studies have been undertaken. However, results of studies concerning
the advantages of today's Hypertext systems over their paper-based counterparts
have shown that many problems still need to be solved if Hypertext is to
fulfill its promises. The Hypertext medium can present few to many advantages
over the paper medium, depending on the task to be performed. We believe that
documentation is an area in which Hypertext should have many advantages over
paper. Because of its very nature, documentation is well suited to non-linear
format. Documentation users are typically looking for specific topics and are
not likely to read the document from cover to cover.
They do not have to adapt their mental models the way they may have to with other forms of Hypertext (such as fiction or learning environments) [2]. Their use of a Hypertext document differs from the paper document only by the medium on which it is presented. Hypertext systems can provide the users with faster and more efficient access and search mechanisms. The purpose of this paper is to identify issues that could significantly influence the use and success of future Hypertext documentation systems and to direct future research. We recognize nine significant issues. We discuss four of the issues in detail and mention the importance and the question raised by the other five issues. | |||
| Hardcopy to Hypertext: Putting a Technical Manual Online | | BIBA | PDF | 67-72 | |
| Vicki Coleman | |||
| More and more companies are delivering their technical documentation online.
A major problem associated with this is how to add value to that online
document so that it will prove useful to the customer. According to William
Horton, "Online documentation requires a way for users to quickly and
conveniently find and display the information they need." [HOR]
One solution to the problem of adding value to and organizing online documentation is the use of hypertext. In fact, "many recent software packages have been delivered with online manuals or online help systems in hypertext form." [NIE] This paper deals with the effort involved in translating a hardcopy Air Force technical manual into hypertext format. The first two sections describe the project involved and the steps taken on first receiving the manual. The next section describes why the basic structure of the manual was not changed, what changes were made to the structure of the manual, and what additions were made. The interface to the expert system is covered next and then a description of the problems that were encountered during the conversion process is discussed. Finally, additional capabilities that the hypertext tool provides are discussed. | |||
| A System for Classification and Control of Information in the Computer Aided Cooperative Workplace | | BIBA | PDF | 73-77 | |
| M. Carl Drott | |||
| After a brief overview of the role of documentation in CACW this paper will discuss CACW documentation which is automatically generated and then follow with an examination of several forms of user supplied documentation, some of which were expected in the design of the system, and some of which arose spontaneously. | |||
| The Hidden Path: Indexing in Information Management | | BIBA | PDF | 78-82 | |
| Chris Hallgren | |||
| This paper addresses the creation of an index as a parallel project to all
other efforts related to developing documentation. This paper views an index
as a collection of strategies designed to ensure the proper depth and scope of
a set of information. The Index Control Log is a phrase invented by the author
to describe the information that results from these strategies over the life of
a software development project. In the opinion of the author, an Index Control
Log should drive and be fed by the design of information in a documentation
project.
On the one hand, an Index Control Log can keep track of the cultural aspects of information through word use. As sophistication grows, the Index Control Log serves as a translation table between different audiences' usage of key terms. Software must fit into a professional context, and, therefore, word use becomes a very sensitive and important area of focus. Not only does each profession have its own "language", but each level of expertise, and each "culture" within each profession (for example, animators within computer graphics artists), has a different syntax, often with confusing meanings for the same words. The Index Control Log is a place to record these variations in usage, and to formulate strategies for word use in the information. On the other hand, the Index Control Log can contain project management information in the form of checklists for the contents of different sections, or for the overall set of information. Every set of information has one or more particular audience levels and demographic qualities to address. Each level of knowledge requires different terms and concepts to aid in learning and use. A properly designed index ("designed" is used intentionally), can aid in shaping information that completely addresses the need of a given audience to explore information, and give it the keys to independently find what they seek. Thus, the title of this paper "The Hidden Path" refers to the success of a set of information, if a seeker, using the language chosen by the index, finds a piece of information in the index, despite being unable to locate it using the organizational tools of the information itself. | |||
| Documenting a Scientific Visualization Tool | | BIB | PDF | 83-87 | |
| Neal W. Johnston | |||
| The First IBM Computer Operations Manual and IBM's 1953 Entry into Electronic Digital Computers | | BIBA | PDF | 88 | |
| R. John Brockmann | |||
| This paper expands upon earlier research reported at SIGDOC '89 on the
1948-52 Eckert Mauchly Computer Company/UNIVAC computer documentation and
examines the work of Sidney L. Lida, the author of the 1953 Principles of
Operation: Type 701 and Associated Equipment -- the first IBM computer
operations manual. This new research seeks to discern whether the
documentation for the 701 (a) reflected the innovations in technology of the
701 itself; (b) was constrained by established IBM documentation paradigms and
thus their target audience's expectations arising from IBM's earlier punch-card
and calculator technology -- after all "Most people, insiders and outsiders,
considered IBM to be a punched-card company", or (c) represented a synthesis of
precedent and innovation as his competitor Chapline had.
*The text of this paper is unable to be printed here because of previous copyright commitments. It will appear in its entirety in Historical Considerations of American Technical Communication (Norwood, NJ: Ablex Publishers, 1992). | |||
| The Challenge of Translating User Data into Workable Documents | | BIBA | PDF | 89-94 | |
| Jennie Dautermann | |||
| Recent emphasis on usability studies in the field of computer documentation
has been justly focused on the understanding of the specific needs of system
users. But the results of such study are not always easily translated into
texts which adequately address user needs. Both the interpretations of
collected data and the implementation of those interpretations into texts
require specific interpretive and adaptive strategies that are often lost
between the mechanics of testing and the many other constraints that drive
document production.
This paper explores the development and use of usability information in a project to provide documentation for a programming language called ISETL. Developed for use in university mathematics classes, this language provides students with a means of learning mathematics through constructing the actual processes of advanced mathematics on a computer. | |||
| A Metric for Hypertext Usability | | BIBAK | PDF | 95-104 | |
| Elmamoun M. Babiker; Hiroko Fujihara; Craig D. B. Boyle | |||
| Many hypertext systems are currently available. Like any other software
system, the usability evaluation of the system plays an important role in the
design and use of the system. Many studies [17] have focused on evaluating
only individual attributes of usability. Therefore, a metric for measuring
overall usability of hypertext system is needed. Such a metric unifies all
individual evaluations into a single measure. It also helps designers identify
problems that hinder users from effective use of their product. In addition, a
metric provides a basis for comparison among hypertext systems.
In this paper, a metric for evaluating usability of hypertext systems is presented. Our focus is on hypertext documentation systems. The metric is based on three important attributes which are important in any hypertext system: access and navigation, orientation, and user interaction. Each parameter is computed based on user performance time, key stroke time and error rate. The usability metric is applied to three different hypertext systems. Our testing has shown that the computed metric values approximate closely the user usability rating. Keywords: Usability, Metric, Hypertext | |||
| A Homunculus in the Computer? | | BIBA | PDF | 105 | |
| R. John Brockmann | |||
| This paper focuses upon is the use of personification and anthropomorphicism
in the development of new technologies. When UNIVAC 1 predicted a landslide
for Eisenhower over Stevenson based on an analysis of early election returns, a
finding that flew in the face of all the human political pundits, Charles
Collingwood refused to believe the findings and told Cronkite on the air:
[UNIVAC] sent me back a very caustic answer. He said that if we continue to be so late in sending him results, it's going to take him a few minutes to find out just what the prediction is going to be. So he's not ready yet with the predictions, but we're going to go to him in just a little while (Shurkin, 252). *The text of this paper is unable to be printed here because of previous copyright commitments. It will appear in its entirety in Historical Considerations of American Technical Communication (Norwood, NJ: Ablex Publishers, 1992). | |||
| Multiple Methods and the Usability of Interface Prototypes: The Complementarity of Laboratory Observation and Focus Groups | | BIBA | PDF | 106-112 | |
| Patricia Sullivan | |||
| Recently, I used a focus group in a usability study of an interface prototype as a balance for a laboratory observation. The clients for this usability study wanted a sense of whether their interface was attractive to a range of users, whether the range of users understood the product, and whether the users could use the interface quickly; they also wanted user feedback on a list of potential features they could include in the next phase of development. Because of very limited resources available for the usability study, and because of the disparate questions the clients had, a focus group for some new users was used to supplement a laboratory observation and interview of other new users. This paper reports on what strengths and weaknesses these methods yielded as complementary approaches to testing the usability of interface prototypes. | |||
| TechWriters: The Next Generation: Distributed Systems and the Changing Roles of Technical Communicators | | BIBA | PDF | 113-118 | |
| Phyllis S. Galt; Susan B. Jones | |||
| In 1988, MIT's central computing organization, Information Systems, created
a Network Services department. Their mission was to enhance and maintain
MITnet, the campus network, and to develop and implement products to be used in
a distributed environment. This group, recently renamed Distributed Computing
and Network Services (DCNS), incorporated some new approaches to software
development and implementation at MIT. One important change was the inclusion
of technical writers on the development teams.
The authors, Phyllis Galt and Susan Jones, worked as technical writers on the first two development projects of Network Services. This paper will describe how the development teams for TechMail, a Macintosh TCP/IP-based electronic mail system, and TechInfo, a public information system, were able to integrate document development into the overall development process, as well as how the writers influenced the interface design. | |||
| Documentation: Dispersed? or Centralized? | | BIBA | PDF | 119-124 | |
| Ronald S. Iseri; Katherine Stevens | |||
| In analyzing how a company produces its documentation, the disposition of
its technical writers is a topic for serious consideration. Frequently, the
options narrow down to two: a centralized department set up specifically to
produce documentation, or a dispersed design, where writers are integrated into
product teams along with analysts, programmers, engineers, or other line
personnel.
Credible arguments and streams of anecdotal evidence can be amassed in favor of one design or the other depending on one's point of view. Such an exercise frequently dwells on the less important aspect of structure and not enough on the important issues of support, management, and individual adaptation. This paper tries to avoid this error while describing one company's experience in moving from a centralized to a dispersed documentation model. | |||
| Quality is Relative: Quality as a Function of Historical Paradigm | | BIBA | PDF | 125 | |
| R. John Brockmann | |||
| Is quality "transcendentalist" soaring above the historical era in which it
is developed, applied, and understood? Or is quality relative to the
communication beliefs of the time?
Three snapshots suggesting the latter will be explored. First we will look at the quality critiques of American sewing machine user manuals of the 1870s and 80s as published in Sewing Machine News and Sewing Machine Advance. These manuals were intended for an audience of women and differ dramatically from the American agricultural technology manuals of the same era intended for men (mower and reaper manuals). Whereas the women's manuals were richly illustrated, and had lengthy explanations with the required actions broken into many steps (a.k.a. "system-style instructional design), the men of the same era, fearful of "book-farming," would only accept very brief un-illustrated instructions hidden away behind advertisements or within spare parts ordering policies (a.k.a. "minimalist instructional design?). What was quality documentation in the 1870s and 1880s? Second, we will observe the dilemma that Hewlett Packard writers faced in the later 1980s when they moved from drafting documentation using the dominant quality paradigm of "specific, clear, and comprehensive" instructions to a new quality paradigm of minimalism in which information is "intentionally incomplete." Why did they have fears of "letting go?" Finally, we will observe why in the early 1990s it had to be a new employee in the intel Corp. who initiated a minimalist approach to hardware documentation that received unprecedented rave reviews from upper level management. *The text of this paper is unable to be printed here because of previous copyright commitments. It will appear in its entirety in Historical Considerations of American Technical Communication (Norwood, NJ: Ablex Publishers, 1992). | |||
| Reader Opinion Cards as a Measure of Customer Satisfaction | | BIBA | PDF | 126-134 | |
| Carol Tyler | |||
| Engineering is convinced the manual is not technical enough. Marketing says
the manuals are too thick. The trade magazine editor who reviewed the product
gave the manual only a fair rating with no elaboration.
Sound familiar? Writers tend to receive a variety of conflicting directions, often with very little real customer input as support. You can be proactive and solicit customer feedback even if don't have a large budget. This paper explains why the Publications department at Intel PCED (the retail part of Intel) began using reader opinion cards as a measure of customer satisfaction, some of the disadvantages to this type of data collection, and finally, bow to create simple reader opinion cards that get responses. | |||
| Ten Steps to Usability Testing | | BIBA | PDF | 135-139 | |
| Marion Hansen | |||
| You believe your company must make its products easier to use to stay
competitive. Management won't hire a human factors or usability testing expert
because they don't see the value. What do you do?
You can be proactive and conduct a usability test to convince the cynics -- even if you don't have a background in psychology, human factors, or testing; a large budget; or a testing lab. This paper covers the basics so that with some work and not much money, you can conduct a decent usability test. Here are the 10 steps that lead to a successful usability test. 1 Do your homework 2 Write the test plan 3 Design the test 4 Arrange a test location and equipment 5 Conduct a dry run 6 Recruit users 7 Set up the test room 8 Conduct the test 9 Compile and analyze the results 10 Take action | |||
| Text in Context: Writing Online Documentation for the Workplace | | BIBA | PDF | 140-148 | |
| Roger D. Theodos | |||
| One key to the usability of technical documentation is the strength of its links to user contexts. These contexts are created by both work and task specific environments. The structure and design of documentation also carries with it contextual meaning. The most useful documents are those in which a consonance exists between the document's context and those of work and task. Hypertext has been touted as a means by which users can create their own document contexts based on their work and task needs. This paper reports on the development of a prototype document designed to test the ability of hypertext to meet the needs of users in a high tech market. | |||
| Using Task Analysis in Documentation Field Research | | BIBA | PDF | 149-153 | |
| Kent Sullivan | |||
| Task analysis, the "systematic analysis of human task requirements and/or
task behavior" (Stammers et al., 1990), is a primary research method used in
the human factors and ergonomics fields to identify and understand the
components of a particular job, set of tasks, or task in a particular context.
Researchers and practitioners in other fields, such as technical writing and
usability testing, have recognized the importance of task analysis in designing
concise, usable documentation, as well as in helping to create intuitive
products. In fact, a technical writer must do some form of task analysis in
order to truly create a task-oriented manual. However, the task analysis
performed is often implicit in the writing process instead of a formal
procedure.
A number of articles about task analysis methods have been aimed at technical writers in recent years, but my research indicates that formal methods are being used very selectively in many companies in the computer industry. (See Berghel & Roach [1990], Bradford [1988], and Leonard & Waller [1989], among others.) While there could be many reasons for this lack of use, my work with several different writing teams at Microsoft points to three possibilities: (1) an assumption that task analysis is primarily valuable when a completely new product is being created, (2) a feeling that task analysis would take too much time for the information it yields, and (3) confusion about what task analysis techniques would be best to use for a given situation and set of questions. In this paper I address these three concerns by describing some first steps I took in adapting task analysis for a usability field research project at Microsoft. The context of my discussion is one phase of a usability field study conducted on a programming product. Specifically, I discuss: 1) The questions the writing team needed to have answered 2) The type of task analysis I chose to use 3) The type of information the task analysis generated 4) How the group of writers (and program designers) used the information 5) Ideas for implementing the method | |||
| Comparing MIS and User Views about Task Needs | | BIBA | PDF | 154-158 | |
| Barbara Mirel | |||
| In this paper, I present findings from research that I conducted on users' strategic approaches to computerized tasks in actual work settings. By examining the ways in which people succeed and fail in manipulating computer systems for their complex, professional purposes, I sought to gain insight into the content and form of documentation that would support strategic interactions with computers. I interviewed 22 users of a financial system in a national research laboratory, users who work on projects funded primarily by the Department of Energy. In the laboratory, about 150 research and development scientists use budget and account data from this mainframe integrated financial system (IFS) to track and manage their project costs. Training on the system and its reports is provided by the Management Information Systems (MIS) department. | |||
| Case Study of Phone Survey for Customer Satisfaction | | BIBA | PDF | 159-167 | |
| Connie Brown | |||
| A small phone survey is one of the best improvement tools a writing group
can have. For a small fee if done by a summer intern, the group can get
reliable measures of customer satisfaction, and reliable directions for
improving the product or service.
This paper briefly presents the methods and results of small phone surveys done in the summers of 1990 and 1991 by an intern at Intel's PC Enhancement Division. | |||