| 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 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
diagrams. * 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. | |||
| 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? | |||
| 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. | |||
| 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. | |||
| 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. | |||
| 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. | |||
| 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 | |||
| 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. | |||
| 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. | |||
| 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). | |||
| 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. | |||