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

ACM Second International Conference on Systems Documentation

Fullname:2nd International Conference on Systems Documentation
Editors:John Browne
Location:Seattle, Washington
Dates:1983-Apr-28 to 1983-Apr-30
Publisher:ACM
Standard No:ACM DL: Table of Contents hcibib: DOC83; ISBN 0-89791-129-6
Papers:17
Pages:107
An automated documentation system for a large scale manufacturing engineering research project BIBAFull-Text 1-10
  Howard M. Bloom; Carl E. Wenger
The Automated Manufacturing Research Facility (AMRF) being implemented at the National Bureau of Standards (NBS) involves the development of a software system integrating the various information processing, communications and data storage functions required in a totally automated manufacturing environment. The project contains a five year software development effort by more than thirty research staff organizationally partitioned into many units working concurrently on different parts of the system and supplemented by software acquired through procurement or contractual effort. As the facility is implemented in modular blocks, new software development will be undertaken as research into factory automation technology continues. The Automated Manufacturing Research Facility (AMRF) being implemented at the National Bureau of Standards (NBS) involves the development of a software system integrating the various information processing, communications and data storage functions required in a totally automated manufacturing environment. The project contains a five year software development effort by more than thirty research staff organizationally partitioned into many units working concurrently on different parts of the system and supplemented by software acquired through procurement or contractual effort. As the facility is implemented in modular blocks, new software development will be undertaken as research into factory automation technology continues.
   In such a research environment, a system is needed for maintaining documentation for the software life cycle for the following purposes: (1) tracking progress of individual module development, (2) allowing for the availability of up-to-date information on module description to other members of the project who need to interface to a given module, (3) developing a cross reference of module and data element relationships, (4) providing a documentation format that includes specific reporting requirements to upper level management, and (5) generating working level documentation that can be easily modified and serve as an up-to-date reference for anyone with interest in the project or special subproject.
   This paper describes the structure of a software system that is functioning in a research environment and satisfies the following design constraints: (I) provide minimum additional effort on the part of the system developers, and (2) reflect the structured thinking of the developer during the software life cycle.
   The key to such a management system is the early documentation of the system modules identified through a decomposition of all functions from the integrated system down to the lowest level subroutines. Each component module of the system has a group of seven documents to track it through the life cycle. The decomposition provides each developer with an understanding of where his module fits into the overall system and permits module documentation to be produced that can be limited to just a few pages. The documenter is encouraged to enter information as it becomes known so that the system always reflects the latest status of the research effort.
   The automated system is being developed as an on-line interactive menu-driven system that allows the developer to enter information about his modules. The final system version will be capable of the following functions: (1) full-screen editing, (2) menu driven interface between the user and the system, (3) cross referencing between module and data elements, (4) generation of reports, (5) generation of work schedules, (6) monitoring of system milestones, (7) checking for appropriate information, and (8) managing a data element dictionary.
'Those silly bastards': A report on some users' views of documentation BIBFull-Text 11-15
  Russell E. Borland
Where has the template tradition in computer documentation led us? BIBFull-Text 16-18
  R. John Brockmann
Keeping the system user's needs in mind how information retrievability was achieved in one reference manual BIBFull-Text 19-28
  Allan Edmands
A standard development process, for user publications BIBFull-Text 29-40
  D. Etz
Use of format models and generic outlines to develop source material BIBAFull-Text 41-46
  Roger A. Grice
This paper describes how format models and generic outlines were used to produce macro and system logic descriptions for the first release of IBM's Distributed Processing Programming Executive (DPPX) during the system's development. Because models and outlines were created and adopted early in the system's development cycle and because project control of both the information and information-developing process were enforced, initial documentation available to system developers was in the same format and of the same quality as the descriptions made available to users after the system was released. The process resulted in higher quality descriptions and less last-minute rework.
   Format models and generic outlines provide a standard description of how the system should be described. In the case of macros, the format model tells the developer how the macro will be described in customer publications and identifies the required information and information formats to be used in the macro's initial description. Following the format ensures that all required information will be included in the initial descriptions of all system macros and that the descriptions of all the system macros will be in the form needed to produce the final descriptions. In the case of system logic descriptions, the generic outline helps ensure that all areas of the system are described in a complete, consistent manner and that there is as little overlap as possible in the system's descriptions.
   Generic outlines and format models help ensure that:
  • Source material will adhere to a specified format.
  • Developers can produce better source material with less effort.
  • Less rewriting is required to convert the source material to final copy.
  • Less review is required to ensure accuracy of the final copy.
  • Developers have final-quality information for their own use.
  • Drafts for review can be produced more quickly and more easily. When a new macro or system component is approved for inclusion in the system, its description is added to the project's internal information data base. The description is modified, if necessary, to fit the required format and is placed in the data base and an entry for it is placed in the data base's table of contents. The description is then available for review, use, and update by all members of the project.
  • The bit bytes the word BIBAKFull-Text 47-50
      Chris Hallgren
    This paper discusses documentation from the vantage point of language. Documentation has several different uses and many different audiences. One method of specifying the systems documentation that must accompany system installation is to involve the users of the documentation in defining the documentation standards. This was done at Simpson-Sears in Canada, and nine different types of documentation groupings were identified, by audience and by use. Some verbal gymnastics were also performed.
    Keywords: Documentation, Systems
    User interface flexibility and limits of effective computer documentation for users BIBAFull-Text 51-53
      Allan J. Henderson
    This paper looks at the increasing flexibility of computer interfaces and the resulting impact on the effectiveness of the computer manufacturer's documentation (reference manuals, training packages, and so on). The paper identifies the types of documentation that begin to lose effectiveness as the user interface becomes more flexible, and briefly looks at ways to keep that documentation as effective as possible.
    An approach to document processing BIBFull-Text 54-56
      Robert Katz
    Toward an electronic programmer's assistant BIBAFull-Text 57-60
      Jeffrey Kurn; Scott L. McGregor
    The purpose of this paper is to describe how an "Electronic Programmer's Assistant" system might be developed initially using currently existing software. The Assistant would be an integrated software package incorporating modules for documentation, automatic programming, and testing. Such an effort requires additional research and definition, and this paper will attempt to describe what existing tools such an effort might use, as well as a broad description of what such a system might offer. While such a system as could be developed in the short term will not solve the autoprogramming problem or the program proving problem, it will be a step in the direction of solutions to such problems. The more modest goals of the system described in this report is to improve the programmer/system designer's productivity in generating and verifying programs.
       The system described here is one which has roots in the growing sophistication of systems for automatic production of systems documentation. Some discussion of the evolution of preceding systems that led to the concepts of the Electronic Programmer's Assistant are also discussed.
    Detailed planning for user publications BIBFull-Text 61-73
      Roberta B. Manz
    Managing for user-friendly publications BIBFull-Text 74-83
      Lawrence C. McKinley
    Bibliographic implication of computer documentation BIBAFull-Text 84-88
      Diana Patterson
    Bibliography is the study of books: how they are made and their physical characteristics. Bibliographers have begun to make some important contributions to the history of ideas, especially with the advent of computerized library information systems. Computer manuals thus far have not been a subject of bibliographic interest and have not been considered worth preserving, even by their authors. Because of the variableness of computer manuals they present special problems to bibliographers, problems which will be intensified by on-line documentation. As computers become the most important communications medium in society the history of ideas will necessarily include the history of computing through its documentation.
    A method to document data entry forms BIBAFull-Text 89-91
      C. S. Sankar
    All of us receive data entry forms manually and electronically. These forms have to be filled and returned. They vary in size, content and clarity. Frequently parts of them are duplicates, but the duplication is concealed by the use of different terminology. The amount of duplicate input will increase sharply in the future, as more and more forms are communicated electronically.
       This paper describes a method to document data entry forms. This method converts a paper form to computerized form, divides the form into data elements, identifies synonyms and replaces them with one preferred term, standardizes mathematical relationships, and arrives at a smaller subset of elements for which actual values have to be input. Once values are input for this limited subset, the method can compute the values for the other derived elements and produce the final filled-in form. All the data elements in the forms are thus documented precisely.
       Six different software products have to be developed and linked together to make this method operational. The work on these is also described.
    Generalized hierarchy chart generator BIBFull-Text 92-96
      Peter J. Thomas
    Documentation writers as screen designers for interactive computer systems BIBAFull-Text 97-101
      Karen Van Dusen; Nichole J. Vick
    For interactive computer systems, most of the communication between users and the computer occurs via the written and graphic information shown on the video display terminal. Let's call that information "the screen," whether it shows text or graphics. Effective communication between the user and the system depends on how well the screen has been designed. One aspect of that design is how the screens, individually and as a whole, have been worded and organized for overall readability.
    Formatting user manuals for use BIBAFull-Text 102-107
      Nichole J. Vick
    Today's documentation specialist writes at a computer terminal, either at a stand-alone word processor or at a terminal of a computer system equipped with word processing software. In recent years, the capabilities of word processing software have expanded rapidly. As a result, most of us have -- as online writers -- tremendous flexibility in how we format the manuals we write.
       Format has come from the realm of the graphic artist in to the realities of the documentation specialist working with a word processor. What used to require typesetting and special graphic skills -- which can be prohibitively expensive for limited-run, frequently updated manuals -- is at our fingertips.
       Now we, as writers, must take full advantage of what we've got. That means applying many of the formatting techniques that visual communicators, such as graphic artists, have known for years. Then we will more fully function as technical communicators.