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

ACM First International Conference on Systems Documentation

Fullname:1st International Conference on Systems Documentation
Editors:Jan Barlett; John Walter
Location:Carson, California
Dates:1982-Jan-22 to 1982-Jan-23
Publisher:ACM
Standard No:ACM DL: Table of Contents hcibib: DOC82; ISBN 0-89791-080-X
Papers:26
Pages:155
Software documentation an automated approach BIBAFull-Text 1-8
  Jonathan Arnon; Harry Lehrhaupt
General Electric has developed a tool and an accompanying methodology that produce documentation as a natural by-product of the software development process. Documentation is generated semi-automatically, is current, and is produced with an estimated one-third savings in design documentation costs.
Function Design Document: Toward better documentation for data processing contracts BIBAFull-Text 9-12
  Steven Brower
Discussions of data processing contracts often emphasize the goals of: 1) negotiating the best possible deal; and, 2) protecting the parties in case of dispute. Considering the expense, delay and frustration wrought by disputes, especially when litigation results, an equally valuable goal is the preparation of contracts in such a way as to avoid disputes.
   The author proposes that this goal be furthered by development of a documentation standard, to be known for purposes of this discussion as a "Function Design Document" (FDD). The FDD would be produced before a contract for software services & products (SS & P)1 was entered into. The FDD would ideally require both parties to clearly define the functionality of the particular SS & P. A contract could then be entered into under which each party knew its own obligations as well as the expectations of the other party.
   Consideration is also given to the way in which the FDD should be handled, from a legal standpoint, since the possibility of a dispute cannot be ignored.
Automating the Technical Publications Department BIBAFull-Text 13-17
  John D. Browne
A DAY AT THE OFFICE -- 1995
   By the time George Denning arrives at his office at Seacom, Inc., at 10:30 a.m. this morning, he has already done three hours of work. George, a Senior Technical Writer in the Software Publications Department, wanted some isolation this morning to edit a particularly tricky section in a user guide. His home computer, hooked up to Seacom's host computer through the local cable network, allowed him to edit the document on-line in the quiet of his den, browse through his company mailbox, and glance at the latest changes to a functional specification Fred Herbert has been working on. Although Fred is the analyst in charge of project development, George is responsible for all ergonomic considerations. Wishing to avoid the chit-chat of a telephone call, George linked up with Fred and the user liaison on the project for a three-way computer conference. In five minutes George had explained the problem he had found, and, with the three looking at the specifications on-line, had changed it to everyone's satisfaction. Finished, George logged off of Seacom and left for the office.
   Arriving at Seacom, George gets a cup of tea and turns on his terminal. The system alerts him that a document has been returned from review. Although the committee members are scattered around the country, it has only taken five days for the entire review cycle. All of the comments have been made on-line. George calls up the review copy on his terminal. The text of the document is formatted on the screen, and blinking red arrows scattered throughout the document show where comments were made. George issues a command, and the document compresses onto the left-hand half of the screen, while the comments appear on the right-hand half. In an hour he has made the changes and sent the file off to the certification board for approval.
   Reviewing the document he edited at home in the morning, George decides an illustration is called for. He queries the Corporate Graphics Library on-line for similar illustrations. The description of one sounds promising. Calling it up on the screen, he decides that, with a few changes, it will fill the bill. Rapidly he draws a few more lines and connectors, adds a photo of a particular device (copied from the corporate photo archives in digital form) and incorporates it into his document as a figure. The system instantly boxes and labels it, and updates the List of Figures in the Table of Contents.
Concept notion for automatic and dynamic thesaurus updating BIBAKFull-Text 18-22
  M. F. Bruandet
We study a methodology for automatic thesaurus construction in order to help the search of documents relevant to a query. This paper aims at presenting how the word-meaning can be analysed automatically, statistically and empirically from discourse data and formally represented as fuzzy subsets of vocabulary, fuzzy relations and classes for thesaurus.
Keywords: Fuzzy sets theory, Information retrieval systems, Knowledge representation, Thesaurus
Piloting electronic mail in today's office environment BIBAFull-Text 23-28
  Bonnie A. Callender; E. David Callender
This paper is a review of the experiences of the authors with electronic mail and is based upon their use of two different electronic mail systems. The first part of the paper contains a review of the attributes of the commercial systems currently available. The second part of the paper is a review of the use of two different electronic mail systems. User response to the electronic mail systems tested is considered to be the key measurement in system acceptability and utilization. The users' expectations, attitudes and responses to the systems are examined. The final part of the paper is a recommendation of how to introduce a pilot electronic mail system into a technically oriented organization.
An evaluation of the AUGMENT system BIBAFull-Text 29-35
  E. D. Callender
For a period of nine months the author used AUGMENT, an electronic office support system. This paper is an evaluation of that system. AUGMENT is a commercially available, time-shared system marketed by TYMSHARE. In an integrated manner, AUGMENT supports functions needed in any electronic office support system. These functions include word processing, electronic mail, computer conferencing and file sharing. It also supports a powerful and unique method of structuring and viewing a file.
   The author was a member of a group of six people who used the system in their daily activities. Many of the major functions of AUGMENT were regularly used during that period. The author found the system to be extremely supportive in his daily activities and believes that it allowed him to materially increase his productivity. The functions that were supported are reviewed and the strengths and weaknesses of AUGMENT as seen by the author are examined.
User manuals: What does the user really need? BIBAFull-Text 36-39
  Roy L. Chafin
The purpose of the user manual is to assist the user in effectively operating a system. This objective is complicated by the wide diversity of user skills, and user tasks. The quality of a user manual is affected not only by the level of effort exerted by the system developer in writing the manual, but also by the degree of matching between the user manual and the user's needs. The documentation writer must supply both effort and direction in writing the user manual. This paper addresses the direction issue.
An automated FORTRAN documenter BIBAFull-Text 40-45
  Timothy E. Erickson
We have written a set of programs designed to help R and D programmers document their FORTRAN programs more effectively. The central program reads FORTRAN source code and asks the programmer questions about things it has not heard of before. It inserts the answers to these questions as comments into the FORTRAN code. The comments, as well as extensive cross-reference information, are also written to an unformatted file. Other programs read this file to produce printed information or to act as an interactive document.
Computers aid index and glossary preparation BIBAFull-Text 46-60
  Ivan Flores
I have written many books but only in the past two years have I had available my own computer and word processor. Now I find the word processor indispensible to my writing endeavors. But my computer can do more than just compose the manuscript. It can help me to compile and organize indexes and glossaries. I have just finished three books and I got assistance from my computer on all of them for the indexes.
   There are four kinds of things my computer does for me:
   1. extracts information directly from the manuscript, providing important words I might want to index;
   2. helps me to make an index file;
   3. puts this file in alphabetic order;
   4. prints out the index in the desired format.
   Some of the help I get is from program packages which I purchase. Other help I get from BASIC programs which I have written to assist me further. I have not seen many articles which describe how to combine purchased software with your programs to facilitate a unified activity.
   First I will describe the system that I have and how I am using it. Then I will tell you what I wanted done in terms of indexes. Finally I will give you the details of the programs I have written and how I use the packages that you can buy.
A software test documentation standard BIBAFull-Text 61-63
  David Gelperin
Software testing (i.e. the process of analyzing the effectiveness and structure of a software item) has two major objectives:
  • 1) to identify the differences between existing and required conditions (i.e. to detect bugs) and
  • 2) to enable the risk of software failure to be accurately estimated. An assessment of risk entails the following steps:
  • 1) Determine the testing results. Which tests succeeded and which failed?
  • 2) Determine the scope and comprehensiveness of the testing process. What testing was done and what testing was not done?
  • 3) Estimate the risk of failure as a function of the test results, the comprehensiveness determination, and past experience with similar products and processes. While the risk function used by a developer and the one used by an acquirer may be different, both functions will require comprehensive data to estimate accurately. Risk assessment requires comprehensive test documentation.
       Such documentation records the plans, designs and results of the software testing process. This record makes testing tangible and permits the process to be managed, and evaluated. Comprehensive documentation enables effective communication, coordination and control. By providing visibility, test documentation enables evaluation of the software and the testing process itself. Evaluation might be made by a developer, an acquirer, a user, an auditor, or a participant in the legal system. Test documentation has many potential users.
  • Documentation production from a formal database BIBAFull-Text 64-77
      Christopher Hartsough; Yuzo Yamamoto; E. David Callender
    This paper reports on an existing, operational prototype system, TG/TF2, for the generation of typeset quality documentation from a formal database. TG/TF2 directly supports the conceptual separation of system design, document content design, and document format design. Specifically, support for system design is supplied by Problem Statement Language/Problem Statement Analyzer (PSL/PSA), a development of the ISDOS Project at the University of Michigan. Document content design support is provided by the Text Generator (TG) language system. Text Formatter, Version 2 (TF2) supports document format design.
       TG is a programming language system specifically tailored for accessing a PSL/PSA database. TG supports document content design through an outline facility that allows the specification of both the order and conceptual content of each section of the document.
       TF2 provides typeset quality output from the text generated by TG. Though similar in flavor to most "pretty printer"/RUNOFF programs, TF2 has been tailored to the requirements of automatic document production without human intervention.
       The paper describes the improvements needed in both concept and implementation before the prototype system can be made into an operational tool. The motivation, genesis, and conceptual basis of TG/TF2 are treated, not the details of the software.
    SAI-SDDLTM ... a tool for automated documentation BIBAFull-Text 78-80
      Donald A. Heimburger; Marcia A. Metcalfe
    SAI-SDDL TM (Science Applications, Inc. Software Design and Documentation Language) is a licensed computer program which aids in the documentation as well as the design of computer software. The three components of SAI-SDDL are: the processor, which is a PASCAL program; the language, which is simple, unrestrictive, and keyword-oriented; and the methodologies, which are numerous and well established. This workshop focuses on the methodologies and the results obtained by applying them.
    Document preparation by an experimental text and facsimile integrated workstation BIBAFull-Text 81-87
      Wolfgang Harak; Wolfgang Postl
    Since '78, an experimental workstation has been built up [1 to 5] at the Siemens Central Research Laboratories at Munich which allows composing, filing, and transmission of illustrated office documents, offering to the user's disposal the following packet of facilities we expect to become standard in the future "paperless" office.
       We decided to design a system model in order to verify this conception by experiment. The result of this design is an assembly of function modules, which, in the general, correspond to peripherals, linked by a local network (scope fig. 1):
  • dialog screen
  • document screen
  • keyboard, for text input
  • tablet, for window control, menu selection, graphics and handprint input
  • printer, for printout of unformatted or formatted text, graphics, and images
  • scanner, for facsimile input of black & white as well as 6gray-level
       images, optionally to by integrated with printer into an intelligent copier
  • harddisk, for system software and temporary storage of user files
  • floppy, for backup, transport and letter mail
  • transceiver, for remote connection. Any of these peripherals can, if required, be duplicated for time sharing users, or for increased performance. Since an essential feature of our system conception is the integration of text and facsimile facilities, we defined the name TEXTFAX which stands as well for the above conception as for the experimental system we are now going to discuss in detail.
  • Chart drawing: A simplified tool for improving computer system documentation BIBAFull-Text 88-92
      Kenneth A. Hough; Larry R. Hart
    This paper takes a different approach to overcoming this documentation problem. The approach taken incorporates within WYLBUR, an on-line program maintenance system, a set of documentation tools for allowing the system designers and programmers to automatically draw the necessary charts, and more importantly, to maintain these charts as the system and program designs evolve. The documentation tools, called Chart Drawing, utilize the facilities of WYLBUR and do not require any additional hardware or software capabilities. The use of the Chart Drawing system also provides standardization in chart presentation and the use of charting symbols.
    On-line documentation for application systems BIBAFull-Text 93-101
      Kimberly Hourigan; Carolyn Stockdale
    A critical factor in application development is delivering timely documentation to the end-user. An interactive solution to the development, maintenance, and distribution of application documentation meets this need. A table-driven software package provides control for three levels of user documentation, forming an immediately available description of application systems in an on-line environment. Users may select any or all descriptive information for a system. At the detailed level the choice is menu driven.
       Documentation levels are:
  • Summary/overview -- provides scope and purpose of system.
  • Detailed operating level -- lists terminal prompts, examples of appropriate
       user responses, and explanatory material to guide the user.
  • News -- brief descriptions of any changes which affect the end-user. Designed for ease of maintenance, the modular file structure facilitates addition, replacement, insertion, and deletion of user documentation. The system allows programmer interaction to install user documentation and provides the system librarian with central control. Features exist which provide documentation status reports and track usage by end-user, giving the librarian tools to determine the priorities with which systems are addressed. Remote high speed printing and terminal display are available for all documentation.
       The paper will describe system specifications, design criteria, and give examples of the implementation.
  • Scope of the OIS/OA project BIBAFull-Text 102-103
      D. D. Lombardi
    WHY is Xerox Computer Services working on Office Automation?
       First, because our national financial picture has seen ever increasing inflation. The cost of almost everything has increased dramatically, including the cost of doing business. A large part of the cost of doing business is administrative costs. Office automation concerns itself with administrative costs of labor (clerical and professional) and time (timely delivery of information).
       When we look at the future, we know that we have to find better ways of getting information from our heads, pens, and typewriters to those who need it. We're not going to be able to rely on once plentiful secretarial or clerical support staff, because we are already feeling a shortfall of these administrative personnel, and in the future, we will see a decreasing population.
       The ability of a company to stay price-competitive in any marketplace hinges on its recognition of the need to automate certain functions within the office, so that employee talent can be applied to successfully achieving the overall goals of the company and meeting new challenges.
    Office automation and the management of change BIBAFull-Text 104-106
      Ann W. Luke
    A period of change in an organization puts our management talents and skills to a true test. When the change is the introduction of new technology or equipment into an existing operation, we need to pay special attention to the way in which we manage the introduction, implementation, training, and feedback of the new system, to ensure that the staff is motivated and informed, positive and cooperative. This paper describes the introduction of information processing systems into the operation of an organization and the special management skills that were brought to bear in introducing and implementing the new technology successfully.
       Of all the things we at Xerox Computer Services learned during the implementation of information processing systems throughout the company, three words stand out: effective management, and communications. These are the critical elements in the introduction of new systems and procedures, and, if used properly, they can lead to a slow, smooth, well-thought-out, and exciting new operation in technology.
    Improving documentation BIBAFull-Text 107-119
      Scott L. McGregor
    The following report focuses on some of the documentation problems faced by many data centers as well as some proposed solutions.
       Many of the difficulties experienced at today's data centers stem from the need to better motivate programmers to generate accurate and useful documentation, and to simplify and standardize documentation tasks.
       This report presents four recommendations to solve these problems. The recommendations are:
  • 1) the creation of a computerized documentation system,
  • 2) the use of matching labels in source code and documentation,
  • 3) the use of tiered documentation formats,
  • 4) the creation of the post of documentation administrator.
  • Word processor to mainframe links: Why, what, and how BIBAFull-Text 120-128
      Marcia L. Meyers
    Many development groups have a mix of standalone word processors and mainframe computers. The main computers may be manufactured by the company or purchased from another company, but they have one thing in common: programmers and engineers use them as vehicle machines for software and/or hardware development. Writers must document how the 'systems' work.
       For the purpose of discussion, we will assume that the mainframe systems are readily accessible to writers as well as engineers and programmers and that they are able to support a number of terminal users.
       The case study presented in the body of this paper is based on multiple main systems, each of which supports 30-40 terminal users, including writers, engineers, managers, and programmers.
    Documentational analysis: Or Good Common Sense BIBAFull-Text 129-131
      Diana Patterson
    Those who never documented their systems are suffering the consequences. In response your friendly marketplace has come up with some solutions to be purchased at the same price as a piece of software. It may or may not be partly software. It is a specific guide for generating documentation in as mechanical and predictable a method possible. If it is mechanical, it can be controlled, and that is what the product is: control. Control of system analysis and design. The necessary by-product is documentation.
       The kind of analysis that documentation requires, falls under that mysterious grace called "Good Common Sense."
    Documentation specialists as a solution to the programmer shortage BIBAFull-Text 132-135
      Stephanie Rosenbaum
    This talk addresses two interlocking problems: the increasing shortage of technical personnel, especially programmers; and the fact that written communication is a necessary task which such people often do not perform effectively. One way to alleviate both problems is to identify certain aspects of the professional programmer's job which involve communication, especially to non-programmer audiences, and then to assign these tasks to professional communicators or documentation specialists.
    Documentation for the casual user: A critical overview BIBAFull-Text 136-138
      Daniel Rosich
    Although common wisdom holds that the ultimate success of any office automation system depends upon end user acceptance, little, if any, attention seems given to the system documentation needed to enable the casual user to use the system properly, efficiently, and effectively. The casual user interacts aperiodically with the system and the interactions are not always a direct requirement of job role; most middle management would be included in this class.
       Several examples of system documentation are reviewed. This paper then attempts to summarize some of the most significant casual user needs and the documentation principles associated with them, to evaluate the applicability of these needs to real-world systems, and to suggest how these needs may be met more effectively.
    System documentation as software BIBAFull-Text 139-142
      Geoffrey James Sickler
    Accuracy, Timeliness, Flexibility, and Low Cost -- computer buyers want BETTER documentation, they want it NOW, they want it to suit THEIR NEEDS, and they want it CHEAP.
       Unfortunately, current documentation methods have failed to satisfy these needs. The inadequacies of the traditional technical manual are well known to anyone who has tried to use one, regardless of the herculean effort it probably took to collect and publish the damn thing. Typically, the resources that could have been expended in making the manual easier to read were expended in an impossible battle to make the information available in a reasonable amount of time, without totally sacrificing the accuracy of its contents.
       The solution to this dilemma lies in changing the way that we view documentation. We must stop thinking of documentation as pieces of paper and start thinking of it as software.
    Alert -- a systems management process BIBAFull-Text 143-150
      Andrew D. Tidwell
    This paper describes a systems management technique used by the Information Systems organization at IBM's Santa Teresa Laboratory. Described is the complexity of the user requirements and the management process used to deliver those requirements from the data processing center. Included is a discussion of the concept of service level commitments and management awareness through various reporting and review techniques. This process is called availability management, which is referred to as ALERT.
    Teaching systems design through systems documentation BIBAFull-Text 151-152
      John P. Walter
    This paper describes a teaching methodology, illustrating:
  • Use of case studies having general appeal to full-time students and
       professional persons,
  • Generally-accepted system documents,
  • A prototype sequence for presentation of each document type,
  • Measures of success of the methodology, and
  • Pitfalls.
  • Development of a computer database to enhance educational and employment access for individuals with disabilities BIBAFull-Text 153-154
      Helen Woodall; Don Warner; Joseph Chiang; Peter Chan; Albert Cook; Lawrence Meyers; Patricia Sonntag
    In order to assist individuals with disabilities in education/employment settings, it may be necessary to provide special devices -- either commercially available or custom made -- so that the person will be able to conduct his/her work properly. In order to obtain these devices, an information retrieval system has been developed that presents the user with various solutions to common problems in communication, mobility, manipulation, and sensory areas.