http://tc.eserver.org/dir/Articles/Documentation/Rhetoric A listing of the most recently indexed works about Articles and Documentation and Rhetoric in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Articles/Documentation/Rhetoric http://tc.eserver.org/35528.html http://tc.eserver.org/35528.html In a case like this, you don’t need documentation made up of perfectly-chosen words and phrases. Instead, you need something that can be easily scanned, easily understood, and easily digested. Documentation that distills the main points quickly. Far more quickly than even the kind of minimalist documentation that I encourage can. http://tc.eserver.org/35212.html http://tc.eserver.org/35212.html Why do product manuals sound formal and stiff-upper-lipped? Why don’t users read manuals? These questions have haunted the precincts of Technical Writing for quite some time now. From what I have seen in Indian writers, I am forced to conclude that English Composition, as we were taught in school, is the culprit. Our merit was based on how verbose we were. They judged our style based on how ‘formal’ we were. Take for example, the leave letter. I am sure you have written a few in school or college. Rewind and replay one of those leave letters. Right from the salutation (Respected Sir/Madam) to the signature (Faithfully/Obediently yours) it reeks of colonialism. And, we have yet to learn our lessons. In this age of globalization (or globalisation, to my stiff-upper-lip comrades), it is important to pay attention to the three Cs: Consistency, Context, and Culture. http://tc.eserver.org/34444.html http://tc.eserver.org/34444.html Why do product manuals sound formal and stiff-upper-lipped? Why don’t users read manuals? These questions have haunted the precincts of Technical Writing for quite some time now. From what I have seen in Indian writers, I am forced to conclude that English Composition, as we were taught in school, is the culprit. http://tc.eserver.org/30815.html http://tc.eserver.org/30815.html How do you go about writing technical manuals for software without going insane? Here are some guidelines you can follow to maintain your sanity when writing software documentation. http://tc.eserver.org/30809.html http://tc.eserver.org/30809.html I know that a lot of people never read instruction manuals or online help. But you know what? Some people do. http://tc.eserver.org/30688.html http://tc.eserver.org/30688.html This study investigates the link between the linguistic principles of implicature and pragmatics and software documentation. When implicatures are created in conversation or text, the listener or reader is required to fill in missing information not overtly stated. This information is usually filled in on the basis of previous knowledge or context. Pragmatics, the study of language use in context, is concerned with the situational aspects of language use that, among other things, directly affect implicatures required of the reader. I investigate how two manuals for the same software product can be analyzed on the basis of implicature and pragmatics. One is an original copy of the documentation that came with the product, the other an after-market manual. Results show that the aftermarket manual requires far fewer implicatures of the reader and does a better job of providing pragmatically helpful information for the user. http://tc.eserver.org/30620.html http://tc.eserver.org/30620.html How can writers enhance their visual literacy in order to create effective online documentation? By partnering multimedia production expertise with technical writing expertise, DVS Communications and Bell-Northern Research (BNR) have co-developed an introductory course 'Words into Pictures' that stimulates visual thinking capabilities. This paper describes the main components of the course and illustrates its contribution to the success of BNR's online information system CADHELP. http://tc.eserver.org/30565.html http://tc.eserver.org/30565.html The need for timely and relevant computer documentation is a constant challenge. Sometimes there is a need to redesign such documentation to make it more useful. Rhetorical analysis is a useful aid for technical communicators in redesigning such documentation. Using Kenneth Burke’s notion of terministic screens, a quick reference aid for the users of a machine-aided translation system is examined from the perspective of graphic communication. Although rhetorical analysis cannot replace accepted principles of good design, it allows the technical communicator to examine design decisions from another perspective, giving one a very different set of questions to consider and some principles of explanation to justify design decisions. http://tc.eserver.org/30385.html http://tc.eserver.org/30385.html A person usually expects another person to behave according to accepted norms, but how does a person respond to a message that violates his/her expectations? One theory dealing with violations of expectations is Burgeon and Hale's (1) nonverbal expectancy-violations theory. This theory posits that, under certain circumstances, violations of social norms and expectations may be an effective strategy for communicators to achieve the intended communication purpose. Although the expectancy-violations theory focuses on expectations for nonverbal behavior, such as gaze and conversational distance (2), I believe that this theory can also apply to expectations for humancomputer interaction. http://tc.eserver.org/29705.html http://tc.eserver.org/29705.html Documentation departments have value; however because of the disconnection with the rest of the company, that value rarely get accurately communicated. Therefore, it is the department’s responsibility to show their value by becoming more visible. This paper describes how one technical writing department overcame negative perceptions by making themselves visible in five different ways. http://tc.eserver.org/27704.html http://tc.eserver.org/27704.html Should instructional texts be purely technical, with a focus on effectiveness and efficiency, or should they also focus on satisfying and motivating users? Good arguments have been made for paying attention to motivational aspects. But only analyses of existing instructions have been published so far, and guidelines for making user instructions motivational have not yet been studied carefully. This article presents motivational strategies and an experiment to test their effects. The results show that motivational elements have little effect on users’ effectiveness and efficiency in performing tasks, their product appreciation, and their self-efficacy, but they do increase users’ appreciation for the instructions. http://tc.eserver.org/24978.html http://tc.eserver.org/24978.html Making documentation more visual is a two phase process. First comes the brainstorming, where ideas bubble up: the weird the funny, the wonderful, the breakthrough, the lame brain — no idea discriminated against, all equally enjoying the bright, spring air of the creative process. Once You begin to brainstorm you may find putting concepts into graphics is easier than you thought. Then comes the second phase: the hard realization that even if you throw out all the crazy ideas, you still have to pick and choose. You have to develop a strategy for graphic use, one that goes beyond the basic visual unity a good graphic designer can give a document. You have to see the graphics in light of the user's need. http://tc.eserver.org/22904.html http://tc.eserver.org/22904.html 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. http://tc.eserver.org/22260.html http://tc.eserver.org/22260.html 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. http://tc.eserver.org/22259.html http://tc.eserver.org/22259.html 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. http://tc.eserver.org/20639.html http://tc.eserver.org/20639.html One important aspect of technical writing is the production and use of procedures. Though technical writing serves a variety of purposes, teaching, informing, persuading, and even questioning, one of its primary and most common purposes is the 'how-to' function of providing procedures. There is a great deal of information available on writing procedures, the vast majority of it focusing on software documentation and product documentation. http://tc.eserver.org/13770.html http://tc.eserver.org/13770.html Mine safety instruction manuals and training guides reflect an engineering perspective based on the concept of a Rational Man, a perspective which obsstructs effective risk management. http://tc.eserver.org/10366.html http://tc.eserver.org/10366.html A very useful perspective for understanding procedural ('how to') discourse and for writing better procedures is to view procedures as a framework of actions and states. The states include desired (goal) states and unwanted states; the actions are user actions, system actions, and external events. This framework underlies all kinds of procedural discourse, including streamlined-step procedures, the model that predominates in online help systems. The components that make up streamlinedstep procedures are best understood as combinations of actions and states. Procedural discourse is also highly rhetorical in nature. We can see the rhetorical implications of actions and states in the various models of procedural discourse, and in specific strategies that writers implement. Because of its terse and rigid nature, the streamlinedstep model is not well suited for certain rhetorical strategies and cognitive goals, and so while recognizing the efficiency of the streamlined-step model, writers should not neglect more