ACM SIGDOC

Pragmatic DITA on a Budget

A small documentation team working on a tight budget can now use the tool ecosystem enabled by the DITA standard to create the sophisticated content that previously required long and expensive projects. The author spent just nine person-weeks over three years to replace a custom XML system with a DITA system based on a combination of off-the-shelf software, authoring conventions, and custom scripts.

Agile Documentation with uScrum

uScrum (uncertainty Scrum) is an agile process developed by a small team at Altitude Software to manage the process of writing user documentation. uScrum manages uncertainty and the unknown, allowing writers to quickly react to changing conditions. uScrum uses orders of ignorance to understand the difficulty of tasks, allowing the team to effectively prioritize regular work together with difficult creative work.

Content Management and the Production of Genres

In this paper, I suggest that granularized content management introduces as-yet-unexplored issues to genres of technical communication. I argue that content management, while it can, as advertised, free content and make it easy to reuse that content in multiple genres, that flexibility can create new problems for genres and genre systems, leading to problematic reuse, inflexible genre systems, rigid and proprietary genres, and uncritical internationalization.

Technical Communication Degrees for the 21st Century

The practice of technical communication, especially for professionals just entering the workplace, is rapidly changing. Companies have higher expectations for degrees in technical communication, a strong foundation in technology, and the ability to function on cross-disciplinary teams alongside technical experts in the design and development process. As the practice of technical communication shifts its focus, academics have the responsibility to be certain that technical communication degree programs have a strong component of such topics as engineering design, programming, human factors, usability, instructional design, and project management, in addition to traditional communication skills. Academic programs have lagged behind practice, largely due to the location of degree programs, departmental reward systems, faculty deficiencies in technology, little depth in fields beyond rhetoric, and lack of exposure to best industry practices. This paper addresses these issues and makes some practical recommendations for catching academe up to practice.

Technologizing Change: Rhetoric of Software Implementation at a University Campus

This paper reports on a study of new software implementation at a university. Seven emails distributed by a central Office of Information Technology were examined for semantic (content) meaning and syntactic (grammatical) function. Semantic findings show a high degree of topical shift. Syntactic findings show a high number of clauses and complements. The analysis also shows how determiners were used to construct 'new' information as 'given' (presupposition). The paper argues that discursive stability was created by technologizing the rhetoric of implementation. The study concludes by suggesting that a heavy reliance on dependent clauses, along with other features, may be indicative of technologized discourse.

How Document Design Helps English Learners Master Science

Explores how basic, scaffolded technical-writing exercises can help ESL students gain cognitive maturity, practice science literacy, improve their note taking, and use text signals and science idioms more effectively.

A Critical Assessment of the Minimalist Approach to Documentation

Carroll's (1991) minimal manual has been considered an important advance in teaching first-time users the basics of computer programs. Unfortunately, it is not very clear what minimalism really means. Practitioners, for example, will find it difficult to create their own minimal manual because the principles of minimalism have not been described in enough detail (see Horn, 1992; Tripp, 1990). It is also not yet settled that a minimalist approach is the most effective one because critical experiments have hardly been conducted. This study therefore closely examines the minimalist principles and claims. This paper describes the basic ideas of minimalism, its design principles and how they can be operationalized. A parallel is drawn between a minimalist and constructivist perspective on learning and instruction. Like minimalism, constructivism places a high value on experience-based learning in context-rich environments. Like minimalism, it stresses the need to capitalize on the learner's prior knowledge as much as possible. And like minimalism, constructivists urge learners to follow their own plans and goals, to make inferences, and to abstract principles from what they experience (see Duffy & Jonassen, 1991, 1992). An experiment is reported that examines the claims of minimalism. Strong and significant gains on several factors were found, all favoring the minimal manual over a control (conventional) manual. The discussion points to several issues that minimalism has yet to address.

Declarative Information in Software Manuals: What's the Use?

Declarative information is often considered to be of little value to software manual users, for two reasons: some research results state that it is consistently skipped by users, and other research results show that declarative information does not enhance task performance. This study puts these conclusions to the test, because the research underlying them does not support such general conclusions. Two experiments are conducted to collect quantitative data about the selection and use of procedural and declarative information and to investigate whether or not the use of declarative information affects task performance and knowledge. A new technique for measuring information selection was developed for this purpose: the click and read method.

Making Sense of Step-by-Step Procedures

Procedural instructions that consist of only a sequence of steps will probably be executable, but nevertheless 'meaningless' to users of technical devices. This paper discusses three features that can make procedural instructions more meaningful: adding functional coordinating information, adding information about the use of the technical device in real life, and adding operational information about how the device works. The research literature supports the effectiveness of the first feature, but offers little evidence that real life elements enhance understanding of instructions. As for operational information, the research suggests that users are willing to read it, and that it contributes to better understanding and performance in the long term, but only if it is closely related to the procedure. As a conclusion, we propose a theoretical framework that assumes three levels of mental representation of instructions: syntactical, semantic, and situational.

Educational Models and Open Source: Resisting the Proprietary University

This paper presents an educational model derived from open source methods for computer programming. The article places this search for an alternative model within a framework of proprietary educational practices that are driven by a need for efficiency and rationalization. As an alternative model, the paper suggests that an open source derived educational process would emphasize collaborative problem based learning, working through drafts, risk taking, mentoring, user testing, releasing early and often. . . .

Full Text Available Documentation, Participatory Citizenship, and the Web: the Potential of Open Systems

Technical communicators have become increasingly interested in how to 'open up' the documentation process - to encourage workers to participate in developing documentation that closely fits their needs. This goal has led technical communicators to engage in usability testing, user-centered design approaches, and, more recently, open source documentation. Although these approaches have all had some success, there are other ways to encourage the participatory citizenship that is implied in these approaches. One way is through an open systems approach in which workers can consensually modify a given system and add their own contributions to the system.

There's More Than One Way To Wire That: When Assembly Workers Are Technically Writers

While technical writing is becoming a more obvious part of undergraduate education, it is not uncommon for an engineer to face the task of writing documentation without much training in the craft of communication. Other members of production teams may have received even less training, and yet have an equal or greater need to have a say in how documentation is produced and what it contains. In this paper, we will examine a situation in which an assembly worker, or system integrator, demanded the opportunity to document the appropriate ways to assemble complex Test and Measurement systems (for evaluating the electronic components of products such as PC’s, cars, and cellular phones), and the effects her change in roles has had on the production processes for both systems and their documentation.

Publishing on the Cheap: One Idea That Worked

For computer centers to eliminate paper documentation is cutting off one’s nose to spite one’s face.

ACM SIGDOC Undergraduate Scholarship

One non-renewable scholarship of $500 will be granted toward school tuition and expenses for the 2003-2004 academic year. The award will be paid directly to the school for crediting to the student's account. To assist a student who is pursuing an established degree program in an area of technical or professional communication. A committee set by the SIGDOC board will evaluate each application with respect to potential future contribution to the field of technical communication. Financial need is not a factor.

Web Design Issues When Searching for Information in a Small Screen Display

In this paper, we report preliminary findings from an experimental study in which twenty-eight users answered questions by performing strategic information searches on web pages. Pages, which varied in length from 100 to 850 words, were displayed on either a standard, desktop monitor (full-sized) or a palm handheld interface (small-screen). Overall, users took more time to perform the tasks on the small screen interface, with the break in efficacy appearing between 225 and 350 word-lengths. Finally, contrary to our hypothesis, participants were similarly accurate across conditions.

Editing Computer Hardware Procedures for Multimedia Presentation

Traditionally, technical editors have ensured consistency in the voice, grammar, and terminology of print documentation. As publications departments have moved to delivering online documentation, the role of the editor has varied and expanded. Editing multimedia documentation requires an even wider scope of skills than editing online documentation.

Hypermedia Systems in the New Millennium

This article revisits three past articles about the implications of hypermedia in the 21st century. Each August, the ACM Journal of Computer Documentation reprints a classic article, book chapter, or report along with several analytical commen- taries and a response by the author of the classic document. In this context, a 'classic' document means one that was published at least five years ago but is no longer in print. It also means one that raises issues of lasting importance to the profession.

Reflections on NoteCards: Seven Issues for the Next Generation of Hypermedia Systems

NoteCards, developed by a team at Xerox PARC, was designed to support the task of transforming a chaotic collection of unrelated thoughts into an integrated, orderly interpretation of ideas and their interconnections. This article presents NoteCards as a foil against which to explore some of the major limitations of the current generation of hypermedia systems, and characterizes the issues that must be addressed in designing the next generation systems.

Successfully Crossing the Language Translation Divide

Going global is a familiar phrase in today’s competitive business environment. When we hear the phrase “going global” what comes to mind? Most of us think of products being sold in a foreign country. Providing documentation in your customer’s language gives your company the competitive advantage in the global marketplace. For those products to be sold successfully, a clear understanding and communication of the language is imperative. Language translation into each target language presents a host of challenges and choices that must be anticipated and resolved in the source language prior to translation.

Cognitive Strain as a Factor in Effective Document Design

People have a limited amount of cognitive resources. Coping with the increasing amount of information presented via a software interface strains a user’s cognitive resources. If a person has to use documentation, whether on-line or paper, additional cognitive resources are consumed, often overloading the user. Using several windows or multi-media elements can compound the problem. Unfortunately, as Wickens (1992) states, humans are unable to manage excessive cognitive strain and they respond by getting frustrated, committing errors, shedding tasks, or reverting to known methods.

Communicating Effectively With Interaction

The ability to build interactions that support, enable, and improve communication is a valuable skill for help developers, Web-site designers, multimedia content developers, information-rich user interface designers-anyone who designs and develops information to be used online. This paper presents the basics of interaction design for information products and describes some basic underlying human factors and user-interface design principles.

Decision Making: A Missing Facet of Effective Documentation

The old school of software interface design and document writing took the view that if the user could find the information someplace, the user could use it. But simply sticking in details ignores how readers access and process information.

Information Design Considerations for Improving Situation Awareness in Complex Problem-Solving

The conventional techniques for task analysis derive the basic tasks that make up user actions. However, in the complex-problem solving environment, attempts to describe step-by-step actions break down because no single route to a solution exists. Although individual tasks can be defined, task-analysis normally results in the tasks being divorced from context. However, to support complex problem-solving, the design must place the information within the situation context and allow users to develop and maintain situation awareness.

Learnability in Information Design

Design of information used for technical communication of complex products should consider how learnable that information is, and strive to deliver materials that are inherently learnable.The speed of information interchange and the demands of the workplace and school curricula require increasingly minimalist approaches to the material that is made available. People are frustrated by long learning times, and new users of software tools demand rapid absorption of tool capabilities. In addition, many readers of technical information are people for whom English is not their native language.Methods and practices that worked in the period when people were willing to commit to hours of study to understand a topic, or days of practice to master a tool, no longer work in a world based on ?internet time.? To assist our understanding of these trends in learning, this paper addresses three key areas related to learnability: proposing a definition of learnability, showing where learnability and usability intersect, and providing a basis for learnability based on some attributes of human beings.

Single Sourcing for Translations

OCLC Online Computer Library Center has reduced costs and improved quality by using single sourcing in the localization of its services. For its FirstSearch reference service (which provides access to 80 databases for 18,000 libraries in 64 countries), OCLC has been through three phases of localization. Each phase has increased consistency and efficiency and lowered our translation costs. In the first phase of localizing FirstSearch in 1999, we introduced French and Spanish versions. The translation included the user interface screens and the help system. During this phase, we had minimal reuse of text in the interface and help files. The next year, OCLC released a major redesign of that service-with three levels of searching and greatly expanded database help. A separate administrative service and help system were also included. The translation task became much larger, and we needed to optimize the opportunities for text reuse in the system interfaces, help systems, and documentation. In the interfaces, all text strings were categorized and defined as entity strings-reused as needed among functions, databases, and user levels. For help and documentation, the needed content was analyzed and defined in an SGML DTD. Scripts were used to generate 240 help topics from a few SGML files. This approach reduced translation costs and facilitated consistency. Now in the third phase of localization, we are integrating our tool set, implementing a content management system, and adding support for Asian languages. Through this phase, we expect to reduce translation costs and improve quality.

"Yes, But Does it Scale?": Practical Considerations for Database-Driven Information Systems

This paper explores the process of designing and implementing a database-driven system of online documentation, and putting it live on the web for customers to use. Using real-life examples, it discusses practical considerations for balancing performance, scalability, and reliability.

Building a Home-Grown Knowledge Base: Don't Wait for the Resources—Build a Prototype

In this presentation, we will discuss why and how we came to build a knowledge base for the Computing Help Desk at MIT. We discuss MIT’s re-engineering effort and its impact on the various Help Desk groups who were brought together as a single team; how this centralizing of Help Desk services created a new requirement of getting useful, just-in-time knowledge to student consultants, and professional staff; and how that requirement helped us approach another goal of our re-engineered processes-helping our customers to help themselves. We then describe the tool we created and how we are using it.

The Changing Face of Technical Communication: New Directions for the Field in a New Millennium

Identifies four different factors shaping the future of technical communication: user-centered design, corporate universities, cross-disciplinary collaboration, and knowledge management. The authors each address how factors once considered external to the field of technical communication are now becoming thoroughly integrated with it. These four studies, in conjunction, suggest how the field of technical communication is becoming increasingly complex and how participants (practitioners, researchers, and educators) will need to adapt to this new terrain.

Finding a Home for Technical Communication in the Academy

The placement of technical communication within an academic curriculum presents an interesting challenge for university administrators and faculty. Technical communication is a young discipline that borrows content from several older, more established disciplines. As a younger discipline, technical communication must combine its borrowed ingredients from other areas into a new and complete offering that can attract research funding for professionals in the academy and deliver job opportunities for its students preparing to enter industry. The credibility of technical communication as a new discipline is dependent on its ability to develop a cohesive body of basic and applied research, its ability to manage technological change, and its ability to promote its identity among an army of competing disciplines.

Annual Awards for Contributions to the Field of Technical Communications

The ACM SIGDOC Executive Board welcomes letters of nomination for the SIGDOC Rigo and Diana Awards. The Rigo Award celebrates an individual's lifetime contribution to the field of information design, technical communication, and online information design; the Diana Award celebrates the contribution of an organization, institution, or business.

ACM SIGDOC (Special Interest Group on Design of Communication)

The ACM Special Interest Group on documentation provides a forum on documentation and user support for computer products and systems. The SIG studies processes, methods, and technologies for communicating information via printed and online text, hypermedia, and multimedia. Members include technical communication professionals, educators, and researchers, as well as system designers, developers, usability specialists, and managers responsible for producing or supervising the creation of documentation, online help systems, and end user interfaces. SIGDOC offers conferences, a high-quality Web site, and The Journal of Computer Documentation, a respected quarterly publication.

Journal of Computer Documentation

This quarterly publication of SIGDOC features refereed original articles and classic reprints, always accompanied by open peer commentary essays and multiple, comparative book reviews.