| 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. | |||
| 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. | |||
| 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. | |||
| 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. | |||
| 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 | |||
| 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. | |||
| 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. | |||
| 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. | |||
| 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. | |||
| Manuals that Meet Market Demands | | BIB | 103-107 | |
| Ladene McClaran | |||
| 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." | |||
| 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. | |||
| 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]. | |||