A directory of resources inthe field of technical communication.


22 found.

About this Site | Advanced Search | Localization | Site Maps



Applying Expectancy-Violations Theory to Online Documentation   (PDF)

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.

Chiu, Yu-Kwong. STC Proceedings (1993). Articles>Documentation>Rhetoric>Online


Creating Procedural Discourse and Knowledge for Software Users: Beyond Translation and Transmission   (peer-reviewed)   (members only)

Although most theorists agree that discourse creates meaning, they have not adequately described how this process emerges within the creation of procedural knowledge. This article explores how technical communicators in diverse settings based discourse decisions on their knowledge of (a) users, (b) organizational image and constraints, (c) software structure and features, and (d) genre conventions in order to create communication artifacts designed to help users develop procedural knowledge. The transformations in which they engaged indicated that these technical communicators were skilled in forming images in these four areas and then using these images as they created meaning in procedural discourse. In this process, they moved beyond merely translating or transmitting technical knowledge.

Rush Hovde, Marjorie. Journal of Business and Technical Communication (2010). Articles>Documentation>Rhetoric>Theory


Creating the Vision: Developing Graphic Strategies   (PDF)

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.

Malone, Jacquelyn. STC Proceedings (1994). Articles>Documentation>Visual Rhetoric


Declarative Information in Software Manuals: What's the Use?   (peer-reviewed)   (members only)

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.

Ummelen, Nicole. ACM SIGDOC (2000). Articles>Documentation>Rhetoric


The Effects of Motivational Elements in User Instructions   (peer-reviewed)   (members only)

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.

Loorbach, N., Steehouder, M., Taal, E. Journal of Business and Technical Communication (2006). Articles>Documentation>Rhetoric>User Centered Design


The Engineer as Rational Man: The Problem of Imminent Danger in a Non-Rational Environment   (PDF)   (peer-reviewed)   (members only)

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.

Sauer, Beverly A. IEEE Transactions on Professional Communication (1992). Articles>Documentation>Risk Communication>Rhetoric


Five Ways to Avoid the “Congratulations” Cliche as You Start a User’s Guide

“Congratulations on purchasing your iPod shuffle.” Have you seen this congratulations sentence before? I see this same pattern of congratulations on almost every manual for products I buy. Could no one think of any other way to kick off the start of a relationship between a product and user? Take the coolest kind of product, an iPod that goes underwater, and then drown the user guide with a cliche.

Johnson, Tom H. I'd Rather Be Writing (2012). Articles>Documentation>Technical Writing>Rhetoric


“Future-Proofing” Our Visual Information   (members only)

Visual information has always been tremendously useful for documentation. The assembly instructions for a piece of furniture from IKEA, for example, are almost entirely graphic so as to minimize translation costs. But graphics also offer challenges when used in online outputs. Should we show graphics in the online help or documentation? Should we show them automatically or link to the graphics and leave it to the viewers to click on the links? What graphic file format is best? How big should the graphics be? And so on.

Perlin, Neil E. Intercom (2011). Articles>Documentation>Technical Illustration>Visual Rhetoric


Genre Ecologies: An Open-System Approach to Understanding and Constructing Documentation   (peer-reviewed)   (members only)

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.

Spinuzzi, Clay and Mark Zachry. Journal of Computer Documentation (2000). Articles>Documentation>Rhetoric


Implicature, Pragmatics, and Documentation: A Comparative Study   (peer-reviewed)   (members only)

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.

Wright, David. Journal of Technical Writing and Communication (2007). Articles>Documentation>Rhetoric>Technical Writing


The Logical and Rhetorical Construction of Procedural Discourse    (peer-reviewed)   (members only)

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

Farkas, David K. Technical Communication Online (1999). Articles>Documentation>Rhetoric


Making Sense of Step-by-Step Procedures   (peer-reviewed)   (members only)

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.

Steehouder, Michael F., Joyce Karreman and Nicole Ummelen. ACM SIGDOC (2000). Articles>Documentation>Rhetoric>Technical Writing


The Personable Manual

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.

Sumankumar R. Indus (2009). Articles>Documentation>Rhetoric


The Rhetoric of Critical Procedures

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.

Boelter, Walter H. Orange Journal, The (2003). Articles>Documentation>Rhetoric>Technical Writing


Rhetorical Analysis of a Quick Reference Aid   (PDF)

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.

Brooksbank, Patricia L. STC Proceedings (1993). Articles>Documentation>Methods>Rhetoric


Twenty-Two Tips for Writing Software Documentation Users Will Actually Read

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.

HelpScribe (2008). Articles>Documentation>Rhetoric>Software


Visible: The New Valuable   (PDF)

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.

Granger, Christine and Austin Skaggs. STC Proceedings (2005). Articles>Documentation>Visual Rhetoric


Visuals Engage Users — Why Aren’t There More Illustrations in Help Content?

While screenshots are important, visuals that illustrate technical concepts are necessary for engagement. Visuals communicate an idea that is otherwise lost in paragraphs of text. Users may skim and scan text, but their focus moves right to visual, because that’s how our brains are wired.

Johnson, Tom H. I'd Rather Be Writing (2010). Articles>Documentation>Technical Illustration>Visual Rhetoric


Why Users Don’t Read Documentation: Technical Writing Secrets

Web documentation does amazing things these days. It lets customers provide direct feedback and lets the company see exactly what search queries which customers are using. That makes it easier to identify information gaps and needs. Companies want to customize the web experience for the user. That is good. But if carried too far, it interferes with the ability to navigate through information.

Nagle, Robert. Idiot Programmer (2007). Articles>Documentation>Technical Writing>Rhetoric


Why Write Instructions That No One is Going to Read?

I know that a lot of people never read instruction manuals or online help. But you know what? Some people do.

HelpScribe (2008). Articles>Documentation>Rhetoric>Technical Writing


Words into Pictures: Applying Visual Thinking to Online Documentation   (PDF)

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.

Couse, Mary M., Malcolm W.J.F. Graham and Louis W. Stokes. STC Proceedings (1993). Articles>Documentation>Online>Visual Rhetoric


Writing Engaging Technical Documentation

Here are some ways to engage users with technical documentation. If you’re skeptical that these techniques are effective, go straight to the content analysis of user ratings. Helping 800,000 users in a year is an impressive number.

Gentle, Anne. Just Write Click (2010). Articles>Documentation>Technical Writing>Rhetoric

Follow us on: TwitterFacebookRSSPost about us on: TwitterFacebookDeliciousRSSStumbleUpon