| An automated documentation system for a large scale manufacturing engineering research project | | BIBA | Full-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 | | BIB | Full-Text | 11-15 | |
| Russell E. Borland | |||
| Where has the template tradition in computer documentation led us? | | BIB | Full-Text | 16-18 | |
| R. John Brockmann | |||
| Keeping the system user's needs in mind how information retrievability was achieved in one reference manual | | BIB | Full-Text | 19-28 | |
| Allan Edmands | |||
| A standard development process, for user publications | | BIB | Full-Text | 29-40 | |
| D. Etz | |||
| Use of format models and generic outlines to develop source material | | BIBA | Full-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 | | BIBAK | Full-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 | | BIBA | Full-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 | | BIB | Full-Text | 54-56 | |
| Robert Katz | |||
| Toward an electronic programmer's assistant | | BIBA | Full-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 | | BIB | Full-Text | 61-73 | |
| Roberta B. Manz | |||
| Managing for user-friendly publications | | BIB | Full-Text | 74-83 | |
| Lawrence C. McKinley | |||
| Bibliographic implication of computer documentation | | BIBA | Full-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 | | BIBA | Full-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 | | BIB | Full-Text | 92-96 | |
| Peter J. Thomas | |||
| Documentation writers as screen designers for interactive computer systems | | BIBA | Full-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 | | BIBA | Full-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. | |||