The readability of technical writing, and technical manuals in particular, especially for second language readers, can be noticeably improved by pairing Theme with Given and Rheme with New. This allows for faster processing of text and easier access to the "method of development" of the text. Typical Theme-Rheme patterns are described, and the notion of the "point of a text" is introduced. These concepts are applied to technical writing and the reader is then invited to evaluate the improvements in readability in a small sample of texts.
Although technical communication documents cannot possibly be tailored to exactly match the interest, reading level and many-faceted influences of a reader, they can I believe, take measures to engage the reader to believe that the information he or she is receiving from the document is valuable to their experience in some way.
“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.
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.
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.
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.
Sometimes, we come across articles on technical subjects that are hard to put down. They even make us ruminate over their content, and talk about them. Though these articles are just for our information, they end up staying in our heart by chance or by design. It is not possible to get so far a reach through the technical coverage alone. The authors have presented them so nicely that we even resist any demand to stop in the middle while reading them. We find such articles mostly in news papers and magazines. As an editor, I have my own reasons for that 'Coup de grâce'! We, the technical writers, can surely pick up some of the clues from our brethren - the journalists.
Connecting people and giving them a place in the world IS (what makes you a living). I immediately thought, this affects technical authors. They connect people to information, rather than people. They help people find their place. They play a role in building and maintaining an organisation's tribe. They show there's more to the supplier-customer relationship than the moment of the sale.
Words, words, words. It seems as if we're being asked to write something every minute for every need and occasion. Your boss wants a report; your colleagues need a memo explaining a procedure; your clients send e-mails that need to be considered and answered; your company's products or services should be described in a descriptive white paper, and on and on. How can you deal with all that? Are there any general writing rules that apply to business writing of all sorts?
A study of how three historical rhetorical concepts (kairos, memoria, and mestiza consciousness) are relevant to professional communication practices today, and productive historical concepts for contemporary practitioners.
Courses and programs in technical writing are both praised and damned for being "practical." But since technical writing is singled out for being practical, it's worth considering what makes it so.
Compelling arguments from researchers studying the rhetoric of science have convinced both scientists and humanists that technical writing involves invention, or discovery of the available means of argument. If we agree that inventio is crucial to technical writing, however, we encounter a problem: namely, that the rhetor engaged in invention as part of a technical writing process does not necessarily have expertise in the subject matter of the composition. What, then, is the expertise that the technical writer contributes to the invention process? Working from the notion that knowledge is an activity rather than a commodity, I argue that a technical writer's expertise in invention lies in an ability to adapt rhetorical heuristics to situations of interdisciplinary collaboration. This focus expands our understanding of how invention works when the goal of communication is producing knowledge across disciplinary boundaries, rather than winning an argument with persuasive techniques.
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.
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.