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

ACM Seventh International Conference on Systems Documentation

Fullname:Seventh International Conference on Systems Documentation
Location:Pittsburgh, Pennsylvania
Dates:1989-Nov-08 to 1989-Nov-10
Publisher:ACM
Standard No:ACM DL: Table of Contents hcibib: DOC89; ISBN 0-89791-337-X; ACM Order Number 613890
Papers:22
Pages:146
  1. Hypertext: A General Discussion
  2. Documentation from the Manager's Perspective
  3. User-Centered Approaches to Documentation
  4. Teaching Analytical and Technical Skills
  5. Hypertext and Online Documentation
  6. Empirical Investigations of Readers' Needs
  7. Strategies for Planning a Documentation Task
  8. Theories of Documentation Development
  9. Supporting and Maintaining Documentation
  10. User-Centered Approaches to Documentation Development
  11. A Question of C.A.S.E.
  12. Hints on the Documentor's Toolkit
  13. Strategies for Planning and Testing Documents

Hypertext: A General Discussion

Designing Hypermedia Help Systems: Problems and Issues BIBA 5-12
  Ayami Ogura; Jennifer Robertson
Over the past few years we have seen a significant increase in hypertext and hypermedia research; the variety of products now available is quite impressive and it seems we are constantly adding newer and even more innovative hypersystems. Clearly, hypermedia is an idea that has captured the imagination of the computer world and many claims have been made for its utility.

Documentation from the Manager's Perspective

Business Planning in Technical Documentation Organizations BIBA 13-19
  David P. Mongeau
Business planning is a process of deciding what an organization will do to be successful, and how it will do it. Business planning can benefit any organization that wants to control its future and to succeed. However, a literature review and some practical experience at AT&T Bell Laboratories suggests that technical documentation organizations have virtually ignored the application of business planning, both as a means of creating their futures and as a means of advancing their profession. The business planning process involves creating an organizational mission; diagnosing the organization's strengths, weaknesses, opportunities, and risks; setting goals; developing objectives and action plans; developing a financial plan; and writing, sharing, and implementing the plan. Following these steps in the Bell Labs Publication Center, we have seen our budget and staff grow and our client base diversify.

User-Centered Approaches to Documentation

Designing Manuals for Hacker Styles of Learning BIBA 21-23
  Barbara Mirel; Susan Feinberg; Leif Allmendinger
Although tutorials in user manuals are an industry standard, findings from recent research challenge the efficacy of a tutorial approach. By tutorial, we mean instructional material that introduces users to the main functions of a program by walking them through the procedures and explanations of a task scenario. While theoretically sound in principle, tutorial instructions are often ineffective in practice because users, faced with actual workplace tasks, have neither the time nor inclination to first work through a tutorial and then return to their actual tasks. Put simply, many users approach on-line tasks with a "hacker" rather than a "tutorial" style of learning.
   Hackers want to solve problems, not learn software. They jump into tasks and hack away at relevant program functions, learning through trial and error. Hackers are often unwilling to read manuals before using an application; however, if referring to a manual is faster and easier than experimenting, hackers will do so when they confront problems.
   Designing manuals to facilitate hacker styles of learning is the focus of a study that we conducted. We tested a nontutorial prototype manual against a tutorial version of the same instructions for a complex query task, that is for selecting only the database records that meet specific conditions. Our results confirm what minimalist manual researchers have found, namely that tutorials are often dysfunctional for active learning styles.
   Manuals should encourage and enhance users' demonstrated learning behaviors rather than expecting users to unnaturally conform to a pre-set tutorial design. Our purpose is to propose what an instructional design must entail if a manual is to effectively accommodate hacker styles of learning.
Rhetoric and Human-Computer Interaction: Investigations into the Writing of User-Centered Documentation BIBA 25-32
  Robert R. Johnson
This paper investigates the need for a user-centered theory of writing documentation. User-centered approaches present new challenges for writers, and it is argued that rhetoric and human-computer interaction are the most appropriate fields for developing a theory to meet those challenges. In addition, applications of the theory are proposed to aid writers in solving common documentation problems.

Teaching Analytical and Technical Skills

A Writing Course in User-Documentation for Computer Science Majors BIBA 33-37
  W. Steve Anderson; John R. Talburt
The problem we present grows out of a simple question: What role should user-documentation play in the curriculum for students in computer science? We are convinced it should have an important rob, and we will explain here how we prepared and taught such a course for this audience.

Hypertext and Online Documentation

Writing On-Line Help when Space is Limited BIBA 39-40
  Jo-Anne Tanenbaum
When the space allowed for on-line help is strictly limited, the writer or manager must decide what information to include, and what to omit. In my experience as an independent documentation consultant, I worked for one client with a severe limitation for on-line help, and one client whose limitation was more flexible. The first client used software that allowed only one screen of on-line help per input field, plus one screen for an overall description. The second client had no software limitation, but wanted the on-line help to be compact enough that the user could look at it quickly.
Creating Effective HyperCard Online Documentation and Training BIB 41-44
  Meryl Natchez

Empirical Investigations of Readers' Needs

The Relationships between Online Help Systems and Print Documentation: An Empirical Investigation BIBA 45-48
  Ali Emdad
Issues addressing the time needed to learn a software system and the effectiveness of the communication between the end-user and a software system have been receiving attention over the past decade [e.g., Emdad, 1988, Pepper, 1981, Way, 1982]. This paper reports on an empirical investigation on the instructional effectiveness of the printed software documentation versus the online help facilities of a software system.
A Survey of Technical Computer Users Resulting in Guidelines for the Development of Technical Computer Documentation BIBA 49-65
  Michael L. Puscas
At present, there is a lack of documentation on the technical information needs, preferences, and attitudes of technical users. Technical users have been inadequately studied, therefore the technical documentation and information needs of this user group are not well understood. If technical users are not well understood, then documentation produced for them may not be satisfying their unique needs important information may be lacking, or information may be inappropriately organized making information retrieval needlessly difficult.
   There is also a lack of documentation on the design, development, and structure of technical documentation. As a result technical computer documentation may not contain the correct content, nor be structured for maximum usability by technical users.
   In short, we don't understand technical users, and therefore we haven't developed technical manuals that meet their needs. This study attempted to provide information on technical users and apply that information to the development of a technical documentation development model.

Strategies for Planning a Documentation Task

The Art of Interviewing a Technical Expert BIBA 67-75
  Sarena B. Green
Interviewing technical experts is an integral part of preparing and writing a technical document. The interview not only determines the content and accuracy of a document but also its organization. Frequently, however, the interview process is frustrating for both the writer (interviewer) and the technical expert (interviewee). Often, it is difficult to elicit needed information from the technical expert for a variety of reasons. This paper explains the tools for conducting a successful one-to-one interview with a technical expert. Interviewing skills and techniques covered include appropriate phrasing of questions, knowing when to listen and when to speak, how to guide the conversation subtly, and how to relax the respondents and get them to volunteer needed information.
   This paper does not examine the process of planning an interview and assumes that you, the writer, have already prepared for the interview. That is, you have prepared a list of questions to ask, made sure that the interviewee is the person who can provide needed information, and if time has permitted, researched and become familiar with the topic.
Sentence First, Verdict Afterward: Finding the Prerequisites for Good Computer Documentation BIBA 77-83
  Andrew Oram; Kathleen Ferraro
Computer documentation reflects the underlying structures and relationships within computer systems. Therefore, successful documentation depends on understanding and interpreting these structures and relationships, not on superficial improvements in writing style, format, presentation philosophy, or technical medium.
   This paper proposes that the research and writing of documentation be driven by the structure of the software. The paper identifies tasks to be performed on the design side of the software, and on the documentation side.
   The most formal and technical part of this paper covers the responsibilities of the engineers, and provides writers with a proposal they can present to their reviewers. This section lists the basic categories of features that engineers must cover (flags, counters, identifiers, table entries, and raw data), as well as what to document for each feature. It is the engineers' responsibility to provide a context for each feature on the system, showing how it would be used in real life.
   Based on this feature-by-feature information, writers must build examples and procedures of gradually increasing complexity. The resulting documents contain immediately applicable information, and are easy to verify and review.

Theories of Documentation Development

Users Invoked: How Documents Help Readers Assume User Roles BIB 85-92
  Mark Simpson
Conceptual Foundations for Computer Documentation: New Distinctions for a New Era BIBA 93-96
  David K. Farkas
Concepts are thoughts made clear and distinct by the distinctions we draw at their boundaries. The concept "conifer" comes about when we begin to make a specific distinction about the features of certain trees. If we cannot formulate such a distinction, we do not have the concept.
   As the computer industry changes, much depends on our ability to formulate new and relevant distinctions and to thereby refocus old concepts and make new ones possible. Otherwise, our overall understanding of our field will diminish and our day-to-day work will in subtle ways become less effective.
   As documentation specialists, our view of the computer industry is necessarily different from that of those who design systems, manufacture systems, or market systems. Thus, we need to carve up the universe in ways that are most useful for our work. At the same time, of course, we have to understand and use the distinctions made elsewhere in the industry.
   The purpose of this paper is to point out four traditional distinctions within the computer industry that are not highly serviceable to those engaged in documentation and to describe refinements upon or alternatives to those distinctions. The distinctions are as follows:
  • (1) Computer systems and noncomputer systems
  • (2) Computer hardware and software
  • (3) Documentation and interface
  • (4) Print and online documentation As we shall see, the distinction between computer hardware and software has always presented significant conceptual difficulties in the area of documentation. In the case of the other distinctions, the difficulties have come about or have been exacerbated by technological change.
  • Supporting and Maintaining Documentation

    A Distributed Architecture for Document Management BIBA 97
      Clifford A. Reid
    TOPIC is a document management system that uses this distributed model of network computing. It uses a variety of caching mechanisms to minimize network traffic, and thereby fully utilizes the distributed processing power of the network clients. TOPIC uses file sharing for shared data access as well as message passing. It supports login security by having each client read an encrypted password file in a shared data area. Infrequent updates to shared databases are implemented using a simple file locking scheme. By limiting its interaction with the network to file sharing, TOPIC is highly portable across networks of UNIX, VMS, and DOS platforms.
    Software Maintenance Documentation BIBA 99-101
      Robert L. Glass
    This paper is about software maintenance documentation. Although user manuals have been perhaps the most spectacular failure in software documentation, maintenance manuals may well be the most costly. Software maintenance consumes well over half of the typical software budget [Glass 81]. Of the maintenance tasks, more time is spent on understanding the software than on any other [Fjelsted 79]. The purpose of software maintenance documentation is to help software maintainers with that (enormously expensive) understanding.

    User-Centered Approaches to Documentation Development

    Manuals that Meet Market Demands BIB 103-107
      Ladene McClaran

    A Question of C.A.S.E.

    Forms Based Documentation to Support Structured Development and CASE Implementation BIBA 109-113
      David Bellin
    One of the most important aspects of structured development is the creation and enforcement of standards. Standards define how a given methodology is to be used within your organization. Examples of standards might include
  • - Which forms and other documents must be bundled together
  • - Steps in the approval process
  • - When and by whom certain project steps must be done
  • - Maximum size of a module of code
  • The Myth and Realities of C.A.S.E. for Documentation BIBA 115-119
      Diana Patterson
    Hypertext seems to be the major focus of user documentation groups, and even some system documentation people. But system developers, engineers and architects are interested in C.A.S.E. More of our documentation work will be coming from or going into C.A.S.E. solutions and integrated systems, and documentation groups should begin to look very seriously at what C.A.S.E. advertises itself to be, what it is in fact, and what role documentors are likely to play in the face of this touted "software development revolution."

    Hints on the Documentor's Toolkit

    Maintaining Multiple Versions of a Document BIBA 121-124
      Amy L. Hinds
    As the software industry continues to release new versions of products, documentation must also coordinate releases of new documentation. Configuration management and version control have been continuous problems for technical documentation groups. Current text editors and publishing systems do not allow an advanced method of conditionally including and excluding information.
       This paper presents a method of tailoring documentation to produce multiple versions of a document from a single source file. This method can be used on UNIX based system with any text processing method, such as LaTeX and Scribe, that requires formatting commands.
    Scribe Support in GNU Emacs BIBA 125-135
      J. Emmett Black
    Think of Scribe as a compiler for a document description language; Scribe is NOT an editor. Scribe is a "high level" document processing system, or a "composition engine" which permits users to deal with documentation at a higher level of abstraction than is possible with "word-processors" or "page processors." One of the methods used to provide this higher level of abstraction is the separation of the "form" or "layout" of the document from the "content;" thus avoiding distraction of the document's author with superfluous details of document format. This frees the writer to concentrate on the content of a document, rather than its format.
       With the increasing popularity of WYSIWYG style editors, which are more properly described as "page processing" systems; fewer people are willing to insert the type of "mark-up" commands required to properly use a "document processing" system such as Scribe. Described herein are a set of support functions, written in a dialect of LISP, which provide assistance to the Scribe user during the preparation and composition of documents. These support functions provide "short-cuts" for insertion of Scribe mark-up, as well as certain features useful during composition and maintenance of large documents. Collectively, these support functions are called "Scribe Mode" and are written to be used with the "GNU Emacs" editor. GNU Emacs is known to run under the Unix and VAX/VMS operating systems, and various versions have been observed to operate on a wide variety of host computers, and other operating systems.

    Strategies for Planning and Testing Documents

    Usability Planning for End User Training BIB 137-142
      David C. Leonard; A. Lynne Waller
    "Executable" Documentation: Testing the Documentation, Documenting the Testing BIBA 143-146
      Fred Ballard
    Too often documentation represents wishful thinking. It is what the designer hopes the program will do. It is what the programmer thinks the program does. It is what the customer wants the program to do. Often little effort is made to check the documentation against what the program actually does. As with many tasks performed in the program development environment, even less effort is made to automate checking the correspondence of expected, documented, results to actual results. This paper will describe a modest effort to allow the computer testing of expected results against actual output in a "literate" style [1].