HCI Bibliography Home | HCI Conferences | DOC Archive | Detailed Records | RefWorks | EndNote | Hide Abstracts
DOC Tables of Contents: 828384858688899091929394959697989900

ACM Eighth International Conference on Systems Documentation

Fullname:Eighth International Conference on Systems Documentation
Location:Little Rock, Arkansas
Dates:1990-Oct-31 to 1990-Nov-02
Standard No:ACM DL: Table of Contents hcibib: DOC90; ISBN 0-89791-414-7; ACM Order Number 613900
  1. Writers and Editors Making the Transition to Online Media
  2. Visual Issues in Technical Communication
  3. Implementing Usability Information
  4. Information Retrieval
  5. From a User's Eye View: Industry, Consulting, and Academic Perspectives on the Development of Online Documentation
  6. Usability Testing: Its Uses and Misuses
  7. Alternatives to Traditional Methods
  8. Development Tools for Information Analysis
  9. A Critique of the Minimalist Approach to Document Design
  10. Documenting the Process, and the Process of Documentation
  11. Organizing Technical Information
  12. Approaches to Self-Documenting Code
  13. Additional

Writers and Editors Making the Transition to Online Media

The Editorial Role in Developing an Online User Interface BIBA 1-16
  Deborah Dameron
As the quality of online systems escalates as a marketing issue, the Editor becomes proportionately more important to the development of a usable and consistent user interface. Editors are vital to the development of a quality user interface for any online system, be it a software product, its accompanying help, or more extensive online documentation. Editors negotiate for quality, lending an experienced eye for detail to each stage of product development, working as part of the Development Team to build a consistent product that meets user needs.
HELPing Writer and Product Team Communication Through Online Document Design BIBA 17-21
  Julie S. McDuffee
As technology advances, software companies must reevaluate and adapt their policies toward product development. The specific product addressed in this paper is an Asset/Liability Management System (ALMS) for the financial industry. The project involves three programmers, who will design and code the ALMS application and one writer, who will design and code an online help system. The end users sees one product, a diskette, that contains both the application and the documentation.

Visual Issues in Technical Communication

Visual Syntax Diagrams for Programming Language Statements BIBA 23-27
  Lisa M. Braz
This paper discusses the following topics:
  • The advantages and disadvantages of using railroad diagrams as opposed to BNF
  • How to determine whether to use railroad diagrams.
  • Converting BNF diagrams into railroad diagrams. The information in this paper is partially based on the results of experiences converting BNF diagrams to railroad diagrams in a 4GL manual for Informix.
  • Implementing Usability Information

    How Do Writers View Usability Information? A Case Study of a Developing Documentation Writer BIBA 29-35
      Patricia A. Sullivan; James E. Porter
    Our study examines how, and to what degree, one writer's rhetorical orientation filters results from usability tests.
  • what is his rhetorical orientation?
  • what value does he place on, and how does he classify and apply, usability
       test information?
  • Information Retrieval

    The Role of Indexing in Technical Communication BIBA 37-40
      Mary Jane Northrop
    The success of a technical document depends heavily on the index. The task of indexing a technical document often cannot begin until insufficient time remains to do a good job. However, for many users of the document, a good index is mandatory to its usability.
       A good index is especially crucial for technical documents because readers tend to look up specific topics instead of reading the document from cover to cover. A poor index often frustrates readers and taints their view of the entire document.
       To create a good index, you have to know what makes a good index, understand the indexing tools available, and follow the steps to producing a good index. Additionally, you must make many process decisions that affect the quality of the final index you produce. The skills and processes for creating a good index are similar to those required for most technical communication projects: methodical approach, knowledge of the users' needs, collaboration with colleagues, and testing.
       This paper discusses how to create a good index and how to make decisions about using personal computer word-processing tools to create an index. It also discusses the feasibility of creating maintainable indexes using these tools.

    From a User's Eye View: Industry, Consulting, and Academic Perspectives on the Development of Online Documentation

    How Usability Testing Can Aid the Development of Online Documentation BIB 41-48
      Mark Simpson
    Putting a Local Information System Online Using Pre-Packaged Software BIBA 49-53
      Jennie Dautermann
    Many small organizations have the need for information storage and retrieval systems which they dream of putting on-line for ease of access. Such a project designed with modest equipment and pre-packaged software can achieve three important objectives:
  • allow users to design their own access tools
  • clarify the information needs of a community
  • improve information access. These goals may be sufficient in themselves in many situations, but they may also become interim steps which prepare users for involvement in larger institutional projects at some later time by enabling them to think through their information needs in concrete and manageable terms.
       During an information management project with the nursing department of a midwest community hospital, a standard PC data base became the vehicle for introducing each of these benefits to the department and for preparing the department to participate in a larger main frame project already in progress in their hospital.
  • User-Centeredness, Situatedness, and Designing the Media of Computer Documentation BIBA 55-61
      Bob Johnson
    Certainly, the research and theory-building of Simon and Newell (2), or G. Polya (3) is applicable to the academic and workplace settings of business, but somehow the terminology of the theory lost its relevance during the translation.
       My purpose in this article is to discuss how user-centered computer documentation can avoid a similar fate. At present I fear our direction is veering in the direction of such a fate, and that one step toward correcting our course is to develop a clear theoretical understanding of what user-centerdness means to documentation. This means that although there may be a tacit theory which underlies current applications, it is important to make the theory visible, and thereby illuminate the gaps that may exist.
       In addition, my focus will also be upon the contribution that user-centered theory can bring to our understanding of how to design for the different media of computer documentation. As we all know, online and hypermedia documentation is becoming a central charge of our profession, and user-centered theory can go a long way in helping us understand the similarities and differences among the different media.

    Usability Testing: Its Uses and Misuses

    Documentation Design Based upon Intuitive Feature Taxonomy and Use Logging BIBA 63-68
      Hal Berghel; David Roach
    Although the quality of documentation of office automation software has increased significantly in the past few years, current offerings are not without problems. Those difficulties which have to do with the design and organization of the documentation are addressed in this paper.
       To illustrate, consider the following situations: 1) the command and control information which is commonly needed is either omitted or hard to find on the 'command card' or 'keyboard template' provided by the vendor, 2) the command or control information which we intuitively feel should be discussed in one section of the manual is actually located in an unrelated section, 3) the manual's table of contents does not seem to correspond well with the functional characteristics of the product, 4) the most appropriate command is not to be found in the manual's index, and 5) the 'help' facility frequently wastes rather than conserves time by providing the user with inappropriate alternatives. We maintain that these sorts of obstructions arise in many cases because insufficient attention has been given to an common sensical and intuitive analysis of the product's functionality as well as empirical use studies. We describe how these difficulties may be overcome by appeal to research results reported in the literature. Word processing software will be used to illustrate the technique.
    Usability and Hardcopy Manuals: Evaluating Research Designs and Methods BIBA 69-77
      Barbara Mirel
    In order to realize the potential of conducting a conversation between pure and applied research, documentation researchers and practitioners must clearly understand the limitations that exist in the conclusions that investigators derive from specific methods of inquiry. In this article, I look solely at experimental usability tests that rely on quantitative methods of analysis. I analyze the ways in which the research designs and questions of the past ten years of experimental studies affect the strength of cumulative conclusions and the confidence we can have in those conclusions. My purpose is not to give preference to experimental research as the most important approach to usability testing. Far from it. Rather my critical review has two purposes: (1) to facilitate the dialogue between academic and industrial researchers by identifying the limits of current experimental findings; and (2) to propose research agendas and designs for future experimental usability tests that can strengthen the conclusions that such researchers offer for practical consideration.

    Alternatives to Traditional Methods

    Document Means More Than Manual: Document Design Outside the Computer Industry BIBA 79-86
      Lorraine Wilkin; Wendie Wulff
    We suggest that some interesting implications for document design in the computer industry can be uncovered by comparing traditional how-to documents with non-traditional ones. In this paper, we will discuss some non-traditional how-to documents, with the intent of contributing to the development of definitions of what how-to documents are and perceptions of how they might be created and/or revised to perform in various situations of use. Through a few case studies, we will contrast the traditional document-as-product approach, the one most frequently found in the computer industry, with the less traditional product-as-document approach which is more familiar to the consumer product and service industries. We will end by describing some implications of the product-as-document approach for practicing document designers in more traditional computer-documentation contexts.

    Development Tools for Information Analysis

    Designing and Prototyping a Portable Hypertext Application BIBA 87-94
      Duane Ressler; Dee Stribling
    At SAS Institute, our diverse, but integrated set of software products added an additional challenge: our ultimate goal would be to create not just hypertext, but hyperdocuments -- online information combining hypertext and hypermedia with other software applications (see Martin, 1990).
       In short, we were faced with the challenge of exploring portable online information applications to document a wide-range of software products. The key question we needed to address was
       "What should our online information actually look like under different operating systems, for different products, and for different segments of our user population?"
       There are many different ways to try and answer this question. For example, you can explore the feasibility of using online information and hypertext by purchasing hypertext software or consulting with outside experts. In any case, it is helpful to be able to explore features and functionality of several different online information applications within your organization before committing resources to either purchasing or developing hypertext software systems.
       This paper discusses how writers and programmers worked together to address this question and others by prototyping hypertext applications using capabilities of existing products available in one software system. Developing within the context of an integrated set of software products provided the additional opportunity to create and test several types of online information; from utility applications to text-intensive online documents.
       The purpose of this paper is to provide insights and suggestions for designing and prototyping portable online information applications gained from this research and development effort. This paper illustrates how you can often combine aspects of different products, taking advantage of features such as screen display management, to simulate and test online information applications before committing to a particular hypertext environment.
       The paper also shows how the concept of hyperdocuments can provide the paradigm necessary to build online information systems that are completely integrated into application-oriented software products as well as serving as stand-alone applications.
    Artificial Neural Networks as Cognitive Tools for Professional Writing BIB 95-110
      Patricia A. Carlson

    A Critique of the Minimalist Approach to Document Design

    The Why, Where and How of Minimalism BIBA 111-119
      R. John Brockmann
    Minimalism is the self-described label that a group of current researchers and writers have given to computer documentation's newest style of writing. It's chief theorist is John Carroll of the IBM Watson Research Laboratories who has published articles about his minimalist experiments over the last six years and has recently packaged them all in a new book by MIT Press, The Nurnberg Funnel, published earlier this summer.
       The basic message of the minimalists is: "Get out of the way of the learner as much as possible":
       The key idea in the Minimalist approach is to present the smallest possible obstacle to learners' efforts, to accommodate, even to exploit the learning strategies that cause problems for learners using systematic instructional materials. The goal is to let the learner get more out of the training experience by providing less overt training structure (Carroll, 1990, Chap. 4).
       And this leads them to do such things as cut 75% of the pages from manuals including overviews, introductions, and summaries.
       But where does minimalism come from? How has it been used by various companies? How does it answer a chronic philosophical problem of user de-skilling in computer user documentation? And, what shortcomings should writers be wary of in minimalism? These are some of the questions this paper will seek to answer.

    Documenting the Process, and the Process of Documentation

    A Stepwise Approach to Developing Software Documentation BIBA 121-124
      Gwen L. Stimely
    Published documentation development processes clearly explain how to break up the process into parts and which parts to do when. What they do not explain is how to merge documentation and software development so that documentation rework and catch-up are minimized. They also do not explicitly account for developing a document from one version to the next, or how to integrate multiple authors into the development process.
       This paper describes:
  • A stepwise approach to customizing standard development processes
  • A customized development process
  • An implementation example of this process
  • Documenting the Software Development Process BIBA 125-133
      June S. Hopkins; Jean M. Jernow
    The Software Engineering Process Group (SEPG) at the Data Systems Division of Litton Systems, Inc., was given the task of documenting the software development process used within the division. This paper describes how the SEPG at Litton accomplished this task. It discusses the sources we used for guidance and describes the resulting documentation for defining the software development process and the methods and tools that support the process.
       After reviewing the existing software process documentation at Litton, the SEPG concluded that three separate documents were required: a revised set of Software Policies and Procedures (PPGs), a Software Engineering Handbook, and a Software Management Handbook. The SEPG established working groups to develop these documents. The working group responsible for the Software Engineering Handbook decided to develop it as a user manual for the software development process. Following Weiss' guidelines for developing a usable user manual, the working group developed storyboards for sections of the manual. A model initially developed at IBM and refined by SEI and others was used to describe the software development process as a series of work tasks, each of which has entry criteria, exit criteria, objectives, and steps to perform.
       Several authors developed the storyboards and the corresponding modules of the handbook. The handbook was partitioned into short modules, each of which has a topic sentence and a figure (where applicable). The result is a modular Software Engineering Handbook that is easy to read and maintain.
       The use of working groups and the development of the Software Engineering Handbook as a user manual proved to be efficient and effective methods for generating high quality software process documentation.

    Organizing Technical Information

    The Mythical Task BIBA 135-139
      Chris Hallgren
    We confront a time in society when phrases such as "information anxiety" have become cliches. As documentation developers, we have a mission to sort information into structures that help users perform their work on computers. Task-based documentation has emerged as one of the most popular models for explaining the principals of sorting information into useful instructions or learning materials. This paper deals with environments where standard task-analysis flounders, either due to the conflicts between different audiences who use the same task elements in different ways, or the complexity of the domain, which makes discrete task modules nearly impossible to define. Under these conditions, we equate the definition of clear tasks with myth -- meaning a symbolic goal more than a real possibility.
       This paper will explore ways to track down the mythical tasks in the information that describes a large, open computer graphics system. This discussion will also serve as a model for analyzing the use of open systems. First we supply the technological history that has led to this information breakdown. Then we present two models from the computer graphics field to use as examples in the application of the theories in this paper. Following this, the paper discusses Tour Books, Tool Books, Job Books, and the importance of both precise and alternate terminology. Finally, it will discuss the usefulness and limitations of indexes, cross references, alphabetic references and hyper text (extended indexes and cross references).

    Approaches to Self-Documenting Code

    An Interactive Source Code Commenter for Prolog Programs BIBA 141-145
      David Roach; Hal Berghel; John R. Talburt
    Prolog meta-circular interpreters, i.e., interpreters for Prolog written in Prolog, perform at least two operations on an object program -- they parse it and execute its instructions. There is a useful variant of the meta-circular interpreter, the meta-circular parser, which as its name suggests, parses an object program without executing its instructions. The value of such a parser is that it provides an elegant means to modify Prolog source code. As the object program is parsed, new information in the form of additional instructions, comments, etc., can be selectively inserted.
       The Prolog source code commenter we describe is a meta-circular parser with facilities added to allow a user to interactively enter comments. As a Prolog program is parsed into its basic components, the user is allowed to view that component and enter an appropriate comment. The result is a new fully commented (and formatted) source program.
    RAP: Relocation Allowance Planner, A Rule-Based Expert System with Self-Defining Documentation Features BIBA 147-150
      John R. Talburt; Hal Berghel; David Roach
    Government employees who are relocating are often eligible for reimbursements for expenses incurred during the relocation process. However, a host of complex government regulations must be examined in order to determine which expenses, if any, are reimbursable. In response to this problem, one set of the regulations, Appendix B of the Health and Human Services (HSS) Travel Manual[6], was encoded into an expert system called RAP: Relocation Allowance Planner[1,7]. Although the user interface of RAP is written in C, the rule base and inference engine of RAP is written in the fifth-generation logic programming language Prolog[3].
       The advent of fifth generation declarative languages and tools, such as Prolog, has had a tremendous impact on application systems development, particularly in the area of intelligent systems. From a systems documentation standpoint, program coding more closely resembles the natural language description of the problem solution than coding in procedural languages such as COBOL and C. Although there are user and system documentation manuals for this system[7], this paper focuses on three of the more interesting self-documenting and self-defining design features incorporated in the RAP system.


    Writing Instructional Materials for Computing Service Courses BIBA 151-156
      Marlene Menard
    A commonly-performed computing task is document production, a job which involves either wordprocessing or text processing. Despite a similar end-product, the two methods differ and a person familiar with only one method is often frustrated when the second one is initially presented. This is particularly true when the person who wordprocesses on a microcomputer is asked to transfer a document to a mainframe computing environment, a place where text processing may be the only means to produce a document.
       To appreciate the frustrations and to develop a solution to problems encountered by the wordprocessing user, it is useful to look at basic differences between the two methods and to focus on the difference in the timing of thinking strategies between each one. While I may try the patience of my readers by defining the two terms, a review from a simple perspective will help recognize the timing differences and will assist with seeing a possible solution to the problem.
    Playing Detective with Full Text Searching Software BIBA 157-166
      Darrell R. Raymond; Heather J. Fawcett
    Searching large text databases often resembles detective work. We explored this notion with an experiment in which subjects used powerful full text searching software to solve problems about the Arthur Conan Doyle story The Hound of the Baskervilles. The experiment was conducted in two parts: in the first part subjects attempted to teach themselves about the software using only the documentation; in the second part, subjects used the software to answer questions such as What brand of cigarette does Watson smoke? The experiment provided a great deal of feedback about the usability of the software and the documentation. Among the results that have wider implications are the need for better display of context, and a need for careful documentation of the characteristics of full text searching.