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

ACM Fourth International Conference on Systems Documentation

Fullname:Fourth International Conference on Systems Documentation
Editors:Diana Patterson
Location:Cornell University, Ithaca, New York
Dates:1985-Jun-18 to 1985-Jun-21
Standard No:ACM DL: Table of Contents hcibib: DOC85; ISBN 0-89791-186-5; ACM Order Number 611850
  1. On-Line: Humans and Computers
  2. Automatic Systems Documentation Generators
  3. Papers
  4. Documentation Recognition and Education
  5. Networks
  6. Language Up [the] Grade
  7. The Computer Medium
  8. Using Human Language
  9. Automatic Documentation with Perspectives
  10. Graphics and Text
  11. A Different Vision

On-Line: Humans and Computers

Separating Content from Form: A Language for Formatting On-Line Documentation and Dialog BIBA 1-7
  Charlie Wiecha; Max Henrion
Recent research has demonstrated the advantages of separating management of the user interface from the application program. A user interface system should integrate access to on-line help and documentation with other dialog for interacting with the program into a uniform environment. We describe such a user interface management system called ICE, with emphasis on its facilities for authoring networks of frames containing help information and menus for interacting with the application program. Authors can write help and dialog using a language similar to the SCRIBE document processing system, widely used at CMU and elsewhere. But instead of generating hardcopy documents for different printing devices, ICE produces interactive "softcopy" documents consisting of a network of frames combining documentation and interface.
   In ICE the screen layout of frames and the style of interaction is specified in a format file which is separate from the dialog file that contains the text to appear in the frames. This separation allows the dialog author to write the text without having to worry much about its precise appearance on the screen. The display designer can specify the actual format independently. The same text can be formatted in different ways to make use of different display devices and to allow experimentation with alternative formats and styles of interaction.
Computer User Manuals in Print: Do They Have a Future? BIBA 8-14
  John B. McKee
What sort of a role will the printed page play in the computer user manuals of the future? I believe that print does have a future in this area, but not perhaps the future we might have foreseen five years ago. At that time nothing was less controversial than the viability of print as a medium of documentation. That viability is in question now, and to show how the questioning developed I propose to examine its beginnings in the recent past. I shall then go into some detail on how the controversy about print is being maintained at present. Finally, I shall explain how I feel the controversy is likely to be resolved, by making four predictions about the future of computer user manuals, and those whose job it is to produce them.

Automatic Systems Documentation Generators

ADL -- A Documentation Language BIBA 15-17
  Richard H. Smith
The problems of documentation began when programming the first program ended.
   In the intervening years much has been done to relieve the programmer's problems. The pioneer programmer struggled with machine language, today he or she uses a relatively tractable high order language, and tomorrow some suggest the programmer will be extinct. "Codeless Programming" is the header line of a new product description of one fourth generation software package [7].
   However, improvements in program documentation have been less dramatic. Progress has been impeded by our difficulty in deciding whether to document at all, whether to do it in earnest, and who should do it. As our views toward documentation evolved over the years, four distinct periods can be identified.
Software Maintenance Documentation BIBA 18-23
  Miheko L. Ouchi
This work aims at presenting a model for assisting in the development of Information System for software maintenance documentation.
   It seeks to emphasize the optimization of the functions related to the documentation, by employing automatic processes.
   In this study the system of documentation is based on a Data Dictionary structure, adequately designed for the organized storage of the information needed for the execution of the maintenance activities.
   Forms of the information input, updating and retrieval have been analysed with the intention of utilizing the basic software of support, as well as to consider the possibilities of the Dictionary interface with the Operating System file, throughout the modification of the application software.
Document Generation from a PSA Database BIBA 24-33
  E. D. Callender; Y. Yamamoto; D. B. Childs; A. M. Farny
During the past five years, we have been using automated tools for producing requirements and design documents. [1] Based on our experiences we have developed a prototype procedure for producing instances of documents automatically from a PSL/PSA database [5] to support system engineering tasks. System engineering is the discipline for designing and developing information systems.
   This paper introduces and describes our prototype procedure for generating automated documentation. The paper is organized into six sections. The remainder of the introduction describes our definition of a document, our distinction between a document type and instance, and the current role of the document in system engineering. Section 2 provides some historical background on the documentation process. Section 3 describes the prototype procedure for document generation currently in use. Section 4 describes an example of a prototype procedure application. Section 5 gives examples of the documents we have generated using our prototype procedure. Section 6 is a conclusion which describes technical issues and future work.
Evolution of Program Documentation Through a Long-Term Project BIBA 34-43
  Peter E. Schilling; John T. Wizzard
This paper is a case study with some recommendations. Over the course of a four-year (twenty person-year) project, the method of documenting programs changed from using separate files containing input data for a documentation lister, to placing all of the program documentation in the source code and using an extraction program when separate documentation was needed. The history and reasons for this evolution are described. The project revealed the usefulness of documentation tools including program templates, a good cross-reference lister, in-line documentation, and the extraction program.


BASIC and DOS Jobstreams in IBM PC Software Documentation BIBA 44-54
  Michael P. Barnett
This paper describes some applications of a programming technique that can be used to produce on-line and printed documentation of BASIC programs written for the IBM PC. The methodology helps to document the usage and other aspects of software, for purposes of review, instruction, reference and general information. The author has used the techniques:
  • (1) to explain the usage of a program by reference to a succession of
        simplified versions which exclude unnecessary details,
  • (2) to construct file driven adaptations of interactive programs for use in
        automated demonstrations, and to run these adaptations,
  • (3) to capture sample displays of text and graphics that illustrate the actions
        of a program,
  • (4) to print batches of programs in formats that are easy to read, and to
        perform other related cosmetic and editorial processes.
  • Designing Computer Documentation that Will be Used: Understanding Computer User Attitudes BIBA 55-56
      Ann Solem
    At the Los Alamos National Laboratory we have over 15 years of experience in designing computer documentation for computer users of the Los Alamos Integrated Computing Network (ICN), which includes five major operating systems. Currently there are over 6,000 users of the ICN: programmers, scientists, technicians, managers, technical editors, and secretaries. They can choose from more than 1,000 printed documents and a variety of online information sources.
       Because of this plethora of information, many users do not know where to find the information they need. And, after finding the right document, they may be dissatisfied by the way the information is presented.
       Over the last few years we studied our computer users and their needs for information. Our objective was to develop a model that could be used to organize the mountain of computer documentation that is needed for complex computer networks.
       In this paper we present the results of this study.
    Better Quality Through Better Indexing BIBA 57-60
      Paula Angerstein
    Readers of technical documentation generally agree that the information in those manuals is only as good as the ease with which they can find it. An informative and accurate index is one of the best tools for helping the reader find information quickly and easily. Yet indexes are one of the most neglected areas of technical documentation, in part because the tools used for creating indexes have not kept pace with other document creation tools.
       This paper discusses the qualities of a good index, and how different index creation tools can hinder or contribute to achieving those qualities. The method developed at Burroughs, which provides capabilities for generating high-quality indexes easily, is described.

    Documentation Recognition and Education

    Documentation's Recognition Problem: What Can We Do About It? BIB 61
      Diana Patterson; Chris Hallgren
    If Writers Can't Program and Programmers Can't Write, Who's Writing User Documentation? BIBA 62-70
      Gregory R. McArthur
    User documentation has been around as long as there have been machines requiring an explanation for their proper use. Instruction sheets, quick reference guides, troubleshooting keys, and owner's manuals are all designed to tell the user, via the written word, what, when, and how to do something with a given machine. With the advent of the computing age (or more specifically, with the invention of the microprocessor), an entirely different type of instruction manual was required; these machines could be made to do things that were user-determined. Not only did the capabilities of the machine itself mandate a description, but so did the functional aspects of the software that ran on the machine. It did not make any difference if you were describing how to operate and manage a large-scale supercomputer or an individually owned personal computing machine; the user needed to be told explicitly how and what to do at both the machine level and the instruction sets or programs that ran on it.
       Writing those guides and other user-oriented computer documentation has been primarily the domain of technical writers and editors. As systems became more complex, the amount of information required to inform a user about their operation grew proportionately, until user guides of some form, in either on-line or hard copy form, have become a de facto documentation requirement. Unfortunately, much of that documentation is now being authored by non-writers: individuals who have had little or no previous experience with writing user documentation, but who have a great deal of knowledge about the underlying software or hardware components. At just the time when users need correct and concise documentation on the systems they acquire, technical writers and editors are being sidetracked into copy-editing or proofreading tasks and requested to make only minor changes to the text written by engineers and programmers. It is time to reverse what may be an incipient and dangerous trend: permitting individuals with no prior technical writing experience to author user documentation.


    An Informal Overview of CUINFO (Cornell's Computer-Based Bulletin Board) BIB 71-77
      Steven L. Worona
    Help Texts vs. Help Mechanisms: A New Mandate for Documentation Writers BIBA 78-83
      Nathaniel S. Borenstein
    To compare different methods of accessing and presenting on-line help, controlled experiments were conducted. Several different help systems were compared, including a natural language help system and a human tutor. The results indicate that, while varying the help mechanism may have some effect on learning, its importance is greatly overshadowed by the simple quality of the help texts being presented. Even for on-line help, good writing seems to be the most important part of helping the user, far more important than elaborate or sophisticated mechanisms.

    Language Up [the] Grade

    Improving Systems Documentation Using an Online Copy Editor BIBA 84-87
      Russell L. Kahn
    For the last three years I have been using Writers Workbench, a UNIX text-editing tool, to edit computer documentation. In this article I outline my experiences using the system, noting both the advantages to explore and pitfalls to avoid in using this tool. Writers Workbench is especially useful for improving a writer's basic skills -- punctuation, spelling, and grammar. When used effectively, Writers Workbench can cut down on wordiness and improve the consistency of a manual. It can help in the creation of a table of contents, index, glossary, and bibliography and in checking readability. Furthermore, by creating user-defined dictionaries, authors or editors can customize the tool to fit their purposes and styles. However, Writers Workbench is not good at catching problems relating to organization, focus, and clarity.
    New Metaphors for Understanding the New Machines BIBA 88-96
      Richard M. Chisholm
    Thought frequently misunderstood and dismissed as irrelevant ornamentation, metaphors are useful tools for writers in the computer industry. Metaphors are especially useful for presenting information about new technologies because they help readers grasp whole concepts immediately and because they illuminate concepts that are difficult to communicate otherwise. It is important to distinguish this use of metaphors from their use in literature and advertisement.
       Participants in the workshop will follow procedures for investigating the suitability of several metaphors. They will analyze the power and appropriateness of metaphors currently used in the computer industry by applying seven criteria: Is the metaphor useful? understood? close? illuminating? acceptable? economical? memorable?

    The Computer Medium

    A Paperless Environment for Group Effort in Document Development BIBAK 97-101
      John A. Cross
    Research into the effect of word processing on writing and a paperless environment for the submission and grading of student assignments has led to considerations for new technology to support the development of system documentation. We assert that a relatively paperless system which integrates the concepts of word processing, electronic mail, computer conferencing and the HANDIN paperless system for student assignments (Cross and Wolfe, 1985) has potential for facilitating the process of developing system documentation. A conceptual framework and specific system features are presented. Research goals and methodologies are briefly considered.
    Keywords: Paperless, Group effort, Computer-mediated communication, Online composing
    Creating a Campus On-Line News System BIBA 102-107
      Pm Weizenbaum
    Information Systems, MIT's campus-wide computing service organization, recently reorganized and strengthened its resources. Out of this recent effort came the decision to explore several ways of reporting on the expanded range of systems and services we offer.
       One service that central computing facilities must provide is timely notice of changes to the supported systems. This paper presents the design and implementation of Information Systems' "On-Line News System", which keeps users updated about changes in the wide variety of services offered by Information Systems.

    Using Human Language

    Factors Affecting Readability BIBA 108-109
      Chris Hallgren
    No one has found a way to really help writers create readable prose. Robert Gunning developed a method for calculating the 'Fog Index' and Rudolph Flesch worked out more than one formula for measuring the simplicity of writing. By one of Flesch's formulas (the one without personal pronouns), Ronald S. Lemos in the February, 1985 issue of Communications of the ACM (CACM) was able to prove that CACM required two less years of school to read than Datamation. Statistics can prove anything. I have no idea what Sophomore in High School could read the CACM cover to cover and even understand most of it.
       Flesch's book 'The Art of Plain Talk' was given to me at a Yourdon Systems Analysis course. The Instructor handed it to each of us, saying something like "read this and you'll be a manager in no time" (supposedly, management is handed to the least efficient person who can also write well). The book is full of examples, mostly journalistic, showing how good writers evoke human interest. Of course, these writers had human events, thoughts and feelings as their focal points, not software, I doubt whether any of the graduates of that week ever used Flesch as a reference for grading their own documentation. How would Bernard Shaw have documented software? Or Mingus played it? This paper addresses these burning issues.
    Documentation: Effective AND Literate BIBA 110-113
      Paul S., Jr. Burdett
    The purpose of this paper is to show how documentation can be literate, in a stylistic sense, and still be effective. Literate prose is a powerful tool that, when properly used in computer documentation, can take advantage of the full power of the English language. This does not mean that all computer documentation must or can read like a Nobel Prize novel, but neither does it have to read like a military cryptogram. A happy medium -- founded on healthy grammar and syntax, and following the logic of the software being documented -- is a good AND obtainable goal.
    The Flesch Index: An Easily Programmable Readability Analysis Algorithm BIB 114-122
      John Talburt

    Automatic Documentation with Perspectives

    Multilingual Programming: Coordinating Programs, User Interfaces, On-Line Help and Documentation BIBAK 123-129
      Gary Perlman
    The high cost of software is not due to the difficulty of coding, but in recoding and redocumenting software. This can be better understood when one considers how many expressions of the same ideas must be constructed and coordinated. Program code and comments, user interface and on-line help, and a variety of off-line documents, all must be consistent. A solution to the coordination problem is presented in this paper. Multilingual programming is a method of developing software that uses a database of information to generate multiple target languages like commented program code, user interface languages, and text formatting languages.
       The method begins with an analysis of a domain to determine key attributes. These are used to describe particular problems in the domain and the description is stored in a database. Attributes in the database are inserted in templates of idioms in a variety of target languages to generate solutions to the original problem. Because each of these solutions is based on the same source database of information, the solutions (documents, programs, etc.) are consistent. If the information changes, the change is made in the database and propagated to all solutions. Conversely, if the form of a solution must change, then only the templates change. In sum, the method saves much effort for updates of documents and programs that must be coordinated by designing for redesign.
    Keywords: Automatic program generation, Automatic documentation, User interface, Language design, Single source of information
    The Impact of Technology on Publishing Through the Ages to You BIBA 130-133
      Diana Patterson
    This paper presents various technological developments from the Rosetta Stone to the Apple Macintosh computer. With the advent of each change the quality of the product decays significantly, and is only restored to something near the glory of the past after a long period requiring much creative endeavour.
       This paper was presented as a slide presentation with extemporaneous comments.

    Graphics and Text

    Merging Text and Graphics BIBAK 134-138
      Judi Cleary
    The capability to merge graphics and text into a consolidated document can greatly enhance communication. Even simple graphics such as boxes and arrows can help organize ideas and make information easier to understand. It is still disturbing to see the number of manuals that describe computer graphics systems that do not include even one graphic image!
       In the phototypesetting world, the capability to merge graphics and text has been available for some time, but only recently have the components for less costly systems become available. This paper will discuss a segmented system in use in a scientific R&D environment for including graphics into documents.
    Keywords: Pixel, Raster, Resolution, WYSIWYG
    Dynamic Screens and Static Paper BIBA 139-145
      Sandra Baissac Smith
    Graphic building design systems in an architectural practice serve a dual role as an effective means of drafting production, and as a visual tool within the creative design process. These systems must allow the same freedom as the traditional pencil and yellow tracing paper. They may be conceived and designed as unstructured systems on several levels.
  • Unstructured Input
  • Unstructured Paths
  • Unstructured Tasks
  • Unstructured Data Each is a source of potential ambiguity, and each affects the documentation effort.
       This paper will discuss the types of problems encountered in creating documentation for such unstructured programs. Questions will be raised as to the approach to printed and on-line reference documents, as well as training. Examples of tasks and documentation will be based on the graphics programs developed by Skidmore, Owings & Merrill (SOM) for the use of its professional staff. These programs process two- and three-dimensional graphic data, interface with plotting devices and with engineering analysis programs.
  • A Different Vision

    A Case History of a Computer Media Event -- Introducing a Supercomputer Center BIB 146-160
      Roger Segelken
    From Pencils and Paste-Ups to VDTs and the Integrated Page: Some Thoughts on the State-of-the-Art BIB 161-164
      Karen E. Andresen