Journal of Computer Documentation

Two Approaches to Modularity: Comparing the STOP Approach with Structured Writing

The first time I heard of the STOP paper was sometime in the mid 80's when the historian of technical writing, John Brockman, phoned me to ask if my Information Mapping method of structured writing derived from the STOP method. At the time I told Brockman that there was no direct relationship between our two approaches since I'd never read the paper. When the editor of this journal sent me the STOP document in preparation for writing this paper, I read it with delight. Although our two innovations date from the same period, the STOP authors and I were working in two completely different disciplines, cultures, organizations, and locations. These two approaches resulted in modularity - albeit of quite different kinds. The main purpose of this project is to compare and contrast these two approaches to modularity. I should note here that I approach this article principally as an exercise in historical comparison, rather than as an exposition of my current views, about which I will say a bit at the end of this article.

Assessing Quality Documents

In recent years, an emphasis on quality has emerged in a variety of organizations and in several fields, including technical documentation. Producing Quality Technical Information (PQTI) was one of the first comprehensive discussions of the quality of documentation. An important contribution of the book is in identifying quality as multiple, measurable dimensions that can be defined and measured (previous views of quality identified it more as some elusive thing that could be identified if present but was difficult to articulate and describe). Despite its contributions to the quality discussion, PQTI runs the risk of simplifying the quality process, reducing quality to a simple checklist that information developers can use to develop effective documentation. PQTI fails to address the fluid nature of some aspects of quality: some dimensions that are important in assessing one document may be less important or irrelevant with other documents. Additionally, PQTI falls short of accounting for the larger contextual framing of documents--that the importance of individual dimensions of quality changes depending upon the audience, context, and purpose of the document.This commentary suggests that all quality efforts should be grounded in customer data and user-centered design processes, and that we should learn to better differentiate among quality dimensions, determining those dimensions that are essential to customer satisfaction and those that are merely attractive. Through increased attention to developing the quality of information, organizations can better differentiate their products and services, facilitate greater productivity, and increase customer satisfactions, all significant activities in an increasingly competitive marketplace.

Commentary on: "Little Machines: Understanding Users Understanding Interfaces"

Online materials, as Johnson-Eilola points out, too often provide speed but neither learning nor conceptual information. Minimum information is often provided in help systems because there are no resources to provide more. But the result is often a system that, without any conceptual information, provides little more than help that is so obvious that it ceases to be helpful. Even when resources are constrained, help systems should, at a minimum, refer to external sources that can help users with important concepts behind the tasks they are trying to perform.

The Metaphysics of Information Quality: Comments on Producing Quality Technical Information

The expressed promise in the title of Producing Quality Technical Information is that following its prescriptions will yield 'quality' technical information. This commentary asks what the term quality means here and whether the manual delivers on its promise. In other words, which of the several senses of quality is intended in the title, and the does the publication deliver as promised? That is, which of the major quality schemes corresponds to the rationale of the text: legalistic quality, in which quality is conformity to a long list of detailed regulations and specifications (as in ISO 9000); principle-based quality, in which quality is the result of working according to a small set of broad precepts; or mystical quality, in which quality is an indefinable property or spiritual construct, toward which virtuous people should aspire.

Notes Toward a Socially Informed Pedagogy for Computer Documentation

This article extends Johnson-Eilola's main argument and then, using a thought experiment, examines an extended example of its implications. The experiment follows a student who learns how to produce technical communication artifacts following the philosophy that informs most technical communication classes and that leads to production of the functional but not conceptual systems Johnson-Eilola critiques. The article concludes by recommending changes in overall curricula and in individual courses that would better educate communicators to account for the social implications of their work

Our Little Help Machines and Their Invisibilities

This paper examines the four kinds of invisibility Johnson-Eilola associates with minimalist help systems: fast information access that reduces user reflection and questioning, impersonal writing style that assumes the Shannon-Weaver communication model, narrow scope that leads to training but not teaching, and interface designs that oversimplify user tasks. For each of the four, the paper questions Johnson-Eilola's conclusions. Ultimately, the problems with truncated online help systems may disappear, as help systems are increasingly linking to the web, where adequate conceptual information is often supplied and opportunities for a social context for help are available.

Quality Technical Information: Paving the Way for Usable Print and Web Interface Design

Principles of information style and design have been around for years. Look at the shelf life of Strunk and White's classic The Elements of Style, published in 1959 and still a bestseller. Producing Quality Technical Information is a gem of a book, whose precise, bullet-style list of seven requirements and a checklist is now even more insightful in the fast-paced world of online information and the World-Wide Web. As a writer, I'm amazed how the IBM authors crystallized the essence of good information design in less than 100 pages. This commentary describes how the book's seven qualities and thirty individual requirements can easily and usefully be extrapolated to address key issues of interface design and usability for today's professional designers and developers.

Response to the Commentaries on Producing Quality Technical Information: The Common Sense of Producing Quality Technical Information

The editor and principal writer of Producing Quality Technical Information (1983) responds to the commentaries: answering questions about the sources of PQTI; discussing what the System Information group at IBM's Santa Teresa Laboratory were doing about usability from 1979 to 1983; comparing the predecessor nine 'ease-of-use factors' with the seven 'qualities' of PQTI and the nine 'quality characteristics' of Prentice Hall's subsequent editions of PQTI, published under the title Developing Quality Technical Information; and revealing his own motives and thought processes in working on several usability initiatives in the laboratory at that time, including the publication of PQTI.

Some Reflections on the Emergence of a Profession

Producing Quality Technical Information played a major role in the shift from product-oriented information to user-oriented information. It brought to a large community of technical communicators an awareness of the role that technical information should play: not a description of a technical product or process but, rather, a description of what people need to do to use the product or perform the process. This shift in focus -- from product to user -- led to many changes in our profession and in our professional careers. No longer mere documentors of what others had done, we emerged as professionals who added value and usability to the project on which we worked.

Counterfeit Capital: Searching for a Silver Lining in Bernadette Longo's Spurious Coin

Dr. Bernadette Longo, Ph.D., uses the metaphor of devalued currency to trace some of the roots in technological history for technical writing's lack of intellectual and cultural capital. She ingeniously incorporates early threads of management and industrial technology, like the formation of the railroad, in an attempt to contextualize her research. Academics must view Longo's text, Spurious Coin, as just one branch of what must be a webbed tree of intersecting social attitudes towards knowledge definition and science. In understanding the gaps in Longo's narrative, people interested in technical writing might find her book to act as a launch pad for better defining the questions guiding their own research. In this review, I will focus on some of the important gaps I see in Longo's research methodology as she historically situates the emergence of engineering as a discipline and then as the determining factor in technical communication's subjugated position within the academy and industry.

Genre Ecologies: An Open-System Approach to Understanding and Constructing Documentation

Arguing that current approaches to understanding and constructing computer documentation are based on the flawed assumption that documentation works as a closed system, the authors present an alternative way of thinking about the texts that make computer technologies usable for people. Using two historical case studies, the authors describe how a genre ecologies framework provides new insights into the complex ways that people use texts to make sense of computer technologies. The framework is designed to help researchers and documentors account for contingency, decentralization, and stability in the multiple texts the people use while working with computers. The authors conclude by proposing three heuristic tools to support the work of technical communicators engaged in developing documentation today: exploratory questions, genre ecology diagrams, and organic engineering.

Introduction to Commentaries on "Spurious Coin: A History of Science, Management, and Technical Writing" by Bernadette Longo

In past issues of JCD, we have employed graduate students in rhetoric and technical communication to provide their point of view on new books in the field. In this issue's book commentary, I have taken this opportunity one more time as students in a graduate seminar at Michigan Tech - Histories and Theories of Technical Communication - read, discussed, and then responded to Bernadette's Longo's Spurious Coin, A History of Science. Management, and Technical Writing.

SIGDOC Reminiscences

By the time I stopped being President in 1993, the sense of computer documentation as a unified whole had ended. When one has such competent folks as Bill Horton writing entire books just on icons, you know that the days of single book coverage…or single SIG coverage were gone forever. Moreover, when the 20,000 member STC decides that it will focus on computers and writing, then the tiny 1200 member SIGDOC gets lost in the welter of talks, papers, presentations, and conventions. So it goes…

SIGDOC Reminiscences

In the few short years that I have been connected with SIGDOC, the world of the technical communicator has changed quite a bit. These changes are visible in several major areas: in the work itself, in the technology and tools that the communicator uses, in the technologies about which they create information, in the work environment, and in the culture in which they operate.

SIGDOC Reminiscences

In the mid 1970's, technical writers documented weapons of mass destruction for the military and its contractors. There were few computer-related jobs outside IBM and the other manufacturers. Corporate systems development managers did not know that people existed who were interested in such work.

SIGDOC Reminiscences

Back in these ancient days SIGDOC was a very relaxed organisation full of personal opinion, and hominess. To give you the flavour of that far off time, I shall present this report as a personal anecdote rather than a proper technical document. Please forgive me, those of you with more formal and well balanced notions of history.

Klare's "Useful Information" is Useful for Web Designers

In many ways the writing principles that Klare recommended 37 years ago to promote high readability scores still apply to web-site design. Behind the pursuit of readability lies audience analysis, a concern with the intellectual level, previous experience, motivation, and reading goals of ones intended audience. Suitably adjusted to take account of online interactivity, those same concerns should guide design work on web structure and interfaces today.

The Measurement Of Readability: Useful Information For Communicators

Discusses the application of readability principles and formulas. It is based upon the survey of the literature presented in succeeding chapters, and represents an interpretation of these data.

Readability and Computer Documentation

Traditional readability concerns are alive and well, but subsumed within several more recent documentation quality efforts. For example, concerns with interestingness and translatability for global markets, with audience analysis and task sufficiency, and with reader appropriateness of technical text all involve readability, but often in ways not easily measured by any formula.

Readability Formulas Have Even More Limitations Than Klare Discusses

A literature review reveals many technical weaknesses of readability formulas (when compared to direct usability testing with typical readers): they were developed for children's school books, not adult technical documentation;they ignore between-reader differences and the effects of content, layout, and retrieval aids on text usefulness; they emphasize countable features at the expense of more subtle contributors to text comprehension.

Readability Formulas in the New Millennium: What's the Use?

While readability formulas were intended as a quick benchmark for indexing readabilty, they are inherently unreliable: they depend on criterion (calibration) passages too short to reflect cohesiveness, too varied to support between-formula comparisons, and too text-oriented to account for the effects of lists, enumerated sequences,and tables on text comprehension. But readability formulas did spark decades of research on what comprehension really involoves.

Readable Computer Documentation

A retrospective look shows earlier advice still relevant to both predicting and producing readable writing. For prediction, refined readability formulas with stronger criterion passages and updated familiar -word lists have appeared, although the computerization of readability tests sometimes encourages misapplying or misinterpreting them when screening text. For production, attention to sentence construction, word characteristics, and information density remains relevant to both drafting and revising computer documentation for readability, especially since reading speed and reader preference often interact with comprehension in practical settings.

Pages, Books, the Web, and Virtual Reality: A Response to Negroponte's "Books Without Pages"

Inclusion of Nicholas Negroponte's paper on 'Books Without Pages' (1979) in this Journal requires explanation, as the paper does not concern itself directly with computer documentation. However, the implications of its assertions and questions ultimately involve all of us who teach, practice, and learn about documenting computer programs. As we leave paper and move to other media to deliver our instructions to users, we are faced with the same questions that Negroponte was asking over 15 years ago. Just as the MIT researchers were doing, we look for new metaphors and new ways to define the relationship between our 'readers' and the information we are providing to them. We search for that perfect controlling metaphor that will clarify how our communications in new media work, and how we can apply some sense and some structure to them, a new 'grammar', if you will, for our books without pages.

A Virtual Conversation on Bernadette Longo's Spurious Coin: A History of Science, Management, and Technical Writing

A collection of responses to Bernadette Longo's Spurious Coin.

The Complexity of Online Groups: A Case Study of Asynchronous Collaboration

Work preparing documents is increasingly being done by diverse, geographically separated project teams. This essay describes some of the characteristics of such collaboration and applies them to a case study involving a team composing a mission statement. The group succeeded in their task, even though shortcomings inherent in asynchronous, distributed collaboration did lead to some problems.

The Ergonomics of Hypertext Narative: Usability Testing as a Tool for Evaluation and Redesign

While usability research concentrates on evaluating informational documents and Web sites, significant insights can be gained from performing usability testing on texts designed for pleasure reading, such as hypertext narratives. This article describes the results of such a test. The results demonstrate that the navigation systems required for such texts can significantly interfere with readers ability to derive value or pleasure from the fiction. The results emphasize the importance of hypertext authors providing more linear paths through texts and of simplifying the navigational apparatus required to read them.

Information Technology and the Emergence of a Worker-Centered Organization

Barbara Mirel's narrative highlights the interplay of profit, power, and personalities in a software engineering project. My response's purpose is to widen the perspective on the story. More specifically, I contend that information technology (IT) enables positive change in today's workplace. Rather than being techno-centric, the re-visions currently being brought about by IT will place the knowledge worker of the 21st century at the center of design and engineering considerations. I support my claim by identifying four trends in organizational management that will afford human factors and usability engineering a better seat at the table in the not too distant future. They are (1) requirements for next-generation IT applications, (2) improved understanding of culture and context in the workplace, (3) recognition of knowledge management and human capital, and (4) fostering strategic leadership beyond resource management.

Little Machines: Understanding Users Understanding Interfaces

This paper questions the ubiquitous practice of supplying minimalist information to users, of making that information functional only, of assuming that the Shannon-Weaver communication model should govern online systems, and of ignoring the social implications of such a stance. Help systems that provide fast, temporary solutions without providing any background information lead to the danger of users completing tasks that they do not understand at all. (Word will help us write a legal pleading, even if we have no idea what one is.) As a result, we have help systems that attempt to be invisible and to provide tool instruction but not conceptual instruction. Such a system presents itself as a neutral tool, but it is actually an incomplete environment, denying both the complexity and alternative (and possibly improved) modes of thinking about the subject at hand.

Product, Process, and Profit: The Politics of Usability in a Software Venture

In research and in practice,usability specialists commonly target the technology user-interfaces and help as the main arena for bringing about usability improvements. However, usability improvements depend on more than innovative and user-centered technical designs and implementations. Equally important for creating useful and usable software are the social and political forces that shape the development context. These forces give rise to leadership conflicts, factional disputes, renegade efforts, alliances and betrayals, all of which profoundly influence whether usability improvements will be supported and sustained within and across projects. This essay presents and analyzes a case history of a software start-up company in which usability achieved a Pyrrhic victory, triumphing only in the short run because of social and political forces.

XML and the New Design Regime: Disputes Between Designers, Application Developers, Authors and Readers in Changing Technological Conditions and Perceptions of Social and Professional Need

This study attempts to: (a) to specify a theory that explains the historical character of change or transition in the production of written artifacts, and (b) use that theory to cast light on a particular instance of change or transition in the production of written artifacts, that of the Web, principally, the issue of structured markup and discussions about precisely what a structured Web should look like, the work it should do, and so forth. It attempts to identify, describe, and analyze, are the norms and conventions that govern the production of written discourse.

Commentary on "Planning and Information Foraging Theories and their Value to the Novice Technical Communicator"

Gattis should be applauded for finding cognitive theories that might be of use to the field, for describing them well with current resources, and for applying them to technical communication with an example. The two theories, however, are too intuitive to provide much value for describing existing behavior or for novices to use as tools.

Mapping the Expanding Landscape of Usability: The Case of Distributed Education

As the environments in which we use technology become more complex and more diverse, we need to extend and expand our notion of usability to include a broad spectrum of users and user activities. We take as an example the case of Rensselaer Polytechnic Institute's distributed education program for human-computer interaction (HCI). While HCI is the subject matter for the courses, the courses themselves present a challenging case study in HCI usability.

Planning and Information Foraging Theories and Their Value to the Novice Technical Communicator

Two complementary cognitive theories help to explain how novice technical communicators learn effective search methods: information foraging theory, a model of information-seeking behavior that combines human-computer interaction with anthropological constructs; and strategic planning theory, a communication model of how humans plan and achieve social goals. The paper includes an extended example of how a new communicator might learn to use both models on the job.

Planning and Information Foraging Theories: Social Implications and Extensions

Information foraging theory and strategic planning theory can help technical communicators think about effective research methods. A broader understanding of social theory can complement Gattis's approach by adding considerations related to underlying ideological assumptions and to how research practices are situated in the larger contexts of organizations, communities, and cultures.

Producing Quality Technical Information

A book about how to produce well-constructed technical writing and illustration.

We Neurotic Amateurs: A Commentary on Edmond H. Weiss's "Egoless Writing: Improving Quality by Replacing Artistic Impulse with Engineering Discipline"

The assertion that technical communicators tend to be 'amateurs'--that is, lovers of our own work--is a claim with little foundation. Arguments toward regimentation and systematization of documentation writing are not calls to professionalize a currently-immature field, but rather attempts to emulate the hierarchy we have seen implemented in microprocessor engineering in the 1970s, software development in the 1980s, and content management in the 1990s. Such 'egoless' methods may offer advantages to employers, but should not necessarily be considered 'progress.'

Egoless Writing: Improving Quality by Replacing Artistic Impulse With Engineering Discipline

When technical communicators have a strong personal attachment to the publication they are preparing, this attachment may interfere with the design and testing of the publication itself. Documents developed by solo authors tend to be late, buggy, and exceedingly difficult for others to maintain. 'Ego-less' methods---collaborative and structured---break the proprietary connection between the writer and the book; in so doing they permit the most powerful tools of engineering and testing to be used. But they also reduce the satisfactions of the communicator's job.

Exploring the Blind Spot: Audience, Purpose, and Context in "Product, Process, and Profit"

Technical communicators have longed turned to audience, purpose, and context as they analyze situations. But Mirel's article demonstrates that audience-purpose-context is too weak a framework to handle the job of detailed sociopolitical analysis: not only is it inadequate for analyzing the needs of end users, it is also inadequate for analyzing situations within the writer's organization. In this response, this paper explores the weakness of audience-purpose-context and points to alternative sociopolitical frameworks.

A Computing Research Repository: Why Not Solve the Problems First?

The Computing Research Repository (CoRR) described by Halpern is potentially a powerful tool for researchers in computing science. In its current form, however, shortcomings exist that restrict its value and that, in the long term, might strongly undermine its usefulness. Important aspects that have insufficiently been taken care of are (1) the quality and consequently the reliability of the material stored, (2) the still restricted submission of material,which implies that other sources have to be consulted by researchers as well, (3) the still unsound financial basis of the project, and (4) the confusion that may easily arise when a preliminary version is stored in the CoRR, while a different final version is published in a journal.

The Dilemma of Credibility vs. Speed

CoRRs implicitly constrained but officially open acceptance policy for submitted papers raises concerns about both censorship and credibility. To avoid refereeing incoming papers yet still help readers assess their merits, CoRR could use coordinated public comments and ratings in the manner of some online auctions and booksellers.

Issues of Online Research Repositories from the Perspective of the Biomedical Sciences

This commentary on Joseph Y. Halpern's proposal for a computing research repository discusses difference in traditions and practices of online publishing and repositories between computing and biomedicals sciences. Issues of accessibility and archiving are also discussed.

Nardi and O'Day's Information Ecologies: Using Technology with Heart

Information. The word has become ubiquitous with the computer and the so-called revolution that has occurred as a result of this electronic gizmo so many of us use on a daily basis. We have linked the word with many other terms to describe how information functions in this new electronically-driven world: information technology, information management, information superhighway. Nardi and O’Day (1999), however, have hitched information to another term—--ecology--—that provides us with another way to think through what it means to work, learn, and play with and through the computer-mediated medium. As with any descriptor that has metaphoric possibilities, inventive minds can conjure a seemingly infinite number of ways to probe the expanded meanings that a metaphor can provide.

At the Heart of Information Ecologies: Invisibility and Technical Communication

The ecological metaphor for technological systems provides a useful supplement to others dealing with the question of human control over technologies. However, it fails to develop adequately its own reliance on communication as the means whereby human values may be embedded in technologies, or to recognize the role of professional communicators in that process.

Confessions of a Gardener: A Review of Information Ecologies

This review of Information Ecologies places the text in the mediating tradition that seeks a middle ground between rigid technological determinism and indifferent value neutrality. The biological metaphors for situated technology use make interesting reading,but the stories may not be compelling evidence that users really can shape technological change from the local level.

Commentary on International Learning

This article, subtitled “Audience Analysis and Instructional System Design for Successful Learning and Performance,” by Margaret Martinez is a must-read for all committed to seeing to it that technologies keep their promises and achieve their potential. There is a propensity among technology proponents to disregard, or at least to minimize the importance of, individual differences among learners and the impact of differences in learning. While the research design, execution, and fi ndings are significant it is important to recognize this work for what it is—a meaningful addition to a less-than-adequate body of knowledge. In our (still) instruction-centered educational environment it is still frustratingly diffi cult to elicit recognition that we are all different in many ways and that includes how we learn. Ms. Martinez has provided us with a contemporary update on individual difference data which flows well from her excellent historical review.

CoRR: A Computing Research Repository

This paper describes the decisions by which the Association for Computing Machinery integrated good features from the Los Alamos e-print (physics) archive and from Cornell University's Networked Computer Science Technical Reference Library to form their own open, permanent, online “computing research repository” (CoRR). Submitted papers are not refereed and anyone can browse and extract CoRR material for free, so CoRR's eventual success could revolutionize computer science publishing. But several serious challenges remain: some journals forbid online preprints, the CoRR user interface is cumbersome, submissions are only self-indexed, (no professional library staff manages the archive) and long-term funding is uncertain.

Expanding Beyond a Cognitivist Framework: A Commentary on Martinez’s “Intentional Learning in an Intentional World”

One of the looming challenges educators face today is understanding how student diversity and uniqueness impacts the complex process of learning. Affective and conative factors are increasingly examined as we seek to understand how to teach and support the whole learner. The goal is to build theory that informs practice so that we may, as Martinez argues, move beyond “fuzzy, one-size-fi tsall [instructional] solutions” to instruction that is designed to match individual learning needs. Factors such as motivation, self-effi cacy, learning styles, and emotional intelligence have become increasingly common terms in educational research as we seek to defi ne affective and conative variables that impact the learning process as well as design of instruction. However, as with much of educational research, there are a vast number of complex, interrelated variables to consider and no one easy solution.

Integrating Academics and Industry: A Challenge for Both Sides

Rapidly emerging technologies are bringing radical changes and challenges to today’s workplace, not just for our own profession but for many others as well. As society’s information needs change, so do the roles of technical communicators. Even the questions technical communicators face are constantly evolving: Which medium to use—and when, and how? Paper or online? Verbal or visual? Such questions were unheard of when many of us entered the profession, but they are commonplace for many practicing technical communicators today (as they certainly will be for many of today’s university students in their careers—and it’s impossible to guess what other questions will be just as routine for them, questions we cannot predict because quite likely the concepts and gadgets and words involved do not yet exist).

Intentional Learning in an Intentional World: Audience Analysis and Instructional System Design for Successful Learning and Performance

How do we support successful, lifelong learners and performers and help them competently respond to rapidly changing opportunities in the 21st century. The answer to this question lies in how well we understand audiences differentiated by key learning differences and consider how these differentiations influence winning learning and performance. Historically, cognitive-rich explanations have tended to underplay the dominant impact of affective and conative factors on thinking and learning. Recently, these dimensions have gained considerable importance as contemporary multidisciplinary research has begun to demonstrate how intentions and emotions can influence, guide, and, at times, override our thinking and other cognitive processes. More importantly, research suggests that intentions and emotions are a dominant, powerful influence on learner success.

Intentionality and Other 'Nonsignificant' Issues in Learning: Commentary on Margaret Martinez’s 'Intentional Learning in an Intentional World'

The backdrop facilitating Margaret Martinez’s study and the increased interest in studies of learners and of alternative learning environments is a complicated one. Most certainly, technological advances during the last decade have invigorated educational institutions and corporate interest in providing alternative educational opportunities for under-represented audiences. Additionally, numerous educational researchers have noted the increased pressure to provide improved educational experiences that are driven by both internal and external pressures on traditional educational institutions.

Bibliography for Performance Systems Technology and Computer-based Instruction

Bibliographies which serve as companions to the two-part article by Reece which appears in the August and November 2000 issues of the Journal of Computer Documentation.