http://tc.eserver.org/dir/Articles/TC/Writing A listing of the most recently indexed works about Articles and TC and Writing in the field of technical communication (and technical writing). 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/TC/Writing http://tc.eserver.org/35843.html http://tc.eserver.org/35843.html Technical communicators tend to get caught up in tools and techniques and formats. But, as Scott Abel said, It’s not about tech writing. It’s about content. http://tc.eserver.org/35838.html http://tc.eserver.org/35838.html Parents spend years trying to teach their children to be polite, and some of us had to learn at school how to properly address an archbishop. Yet, it seems that advice on courteousness and politeness in technical communication is in short supply; most of us learn these skills through what is euphemistically called “on the job training.” With enough bruises on my back to demonstrate the amount and variety of my experience in this area (though not my skill), here are some of the things I’ve learned. http://tc.eserver.org/35788.html http://tc.eserver.org/35788.html Sometimes, 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. http://tc.eserver.org/35529.html http://tc.eserver.org/35529.html A huge problem for projects is the lack of a common language between the developers and the users. When my colleague and I were preparing a presentation for an internal conference on this subject, he said something that has stuck with me. He said, “The goal of the project is to make the user successful.” I added to that: It’s not to write code or validate code. It’s not even to ship a product or make money (of course, this last one is especially true in a non-profit organization). At least, it shouldn’t be these things. http://tc.eserver.org/35510.html http://tc.eserver.org/35510.html Radio and documentation. It sounds like a strange, if not incompatible, mix. But as Scott Nesbitt explains, an ideal model for writing documentation is a good radio report. http://tc.eserver.org/35124.html http://tc.eserver.org/35124.html In this post, technical writer Milan Davidovic that contributing to wikis can help novices build skills and a portfolio. And he offers a simple roadmap for doing that effectively. http://tc.eserver.org/34918.html http://tc.eserver.org/34918.html In a profound sense, the teaching of business and technical communication (BTC) is always already the teaching of writing in the disciplines (WID). Yet the WID dimension of BTC is often hard to see. The question this article addresses is, How might the North American tradition of BTC communication courses be more consciously—and effectively—articulated with the disciplines? The article reviews some of the research literature concerning the value of articulating BTC with WID in undergraduate education and program descriptions of such efforts to examine what BTC has done, is doing, and might do in the future to strengthen WID in BTC. http://tc.eserver.org/34898.html http://tc.eserver.org/34898.html Although we look at the past with embarrassment about some of our practices, we often lack the foresight to see the present with the same degree of scrutiny. Years from now, we’ll look back at what we’re currently doing and not only blush, but feel remorse and wish we could get back what we lost. http://tc.eserver.org/34695.html http://tc.eserver.org/34695.html In the absence of safety concerns, I think that accuracy must win. Thus, as the information curator, you have a responsibility to correct inaccurate information. If the inaccuracy is truly dangerous, you may need to edit the post directly. Make sure that you disclosure what you've done with brackets. http://tc.eserver.org/34543.html http://tc.eserver.org/34543.html The Twitter Book was created as being a different approach to publishing. But it’s also a different approach to writing. And that approach has definite applications in technical communication. http://tc.eserver.org/34263.html http://tc.eserver.org/34263.html Twitter can be a great tool, and can help people get answers quickly. However, when you have a question and need an answer, you probably ought to consider your question, and determine what channel is best suited for the type of answer you need. That may or may not be Twitter. http://tc.eserver.org/34253.html http://tc.eserver.org/34253.html The online transition to web 2.0, with its proliferation of blogs, wikis, podcasts, tweets, and other user-generated content, has posed a question for the state of help content. Should help material concern itself with web 2.0? Do users want to interact and contribute to help content in the same way they contribute and interact with web content? What is the technical writer’s role in relation to new media? http://tc.eserver.org/34130.html http://tc.eserver.org/34130.html With the passing of the Brayley Bill in Congress, the significance of plain language has become even more apparent to technical communicators. The author lays out a step-by-step plan to maintain the relevance of plain language as an important and necessary profession. http://tc.eserver.org/32137.html http://tc.eserver.org/32137.html Technical communication must ultimately serve the reader - there must be something that the writer can do to clarify the information and make reading part of the process that makes the product usable. http://tc.eserver.org/31983.html http://tc.eserver.org/31983.html This article is about better commenting practices for the purpose of—perhaps—helping some to better their programming practices. But before beginning, let me qualify the entire thing by saying that I am not a programmer—not the professional kind anyway. I have created small programs in the past for some of my employers, but that is not how I make my living. Therefore, I am not trying to teach principles of programming. I am only a writing teacher who happens to enjoy programming as a hobby. And while I cannot provide insight into better programming principles, I can offer guidance about writing those short pieces of text programmers always embed, but sometimes neglect. Helping students write better documents is, after all, my occupation; and believe it or not the principles I teach to write better papers are not that different from the principles needed to write better code. http://tc.eserver.org/31883.html http://tc.eserver.org/31883.html User documentation is rarely, if ever, read like an ordinary book. Readers jump around, finding the information that they need to perform a particular task and pretty much ignore the rest. Until they need that information, of course. http://tc.eserver.org/31794.html http://tc.eserver.org/31794.html This blog post ponders whether or not technical communicators are sometimes too enamoured with the tools, and because of that lose sight of what's best for the reader. http://tc.eserver.org/31739.html http://tc.eserver.org/31739.html The best thing you can do to develop your skills and ability with technical writing is to actually do some technical writing. Find an open source project, such as WordPress.org or Pligg, and write some documentation for it. Most open source projects have poor documentation, so they provide excellent opportunities. http://tc.eserver.org/31143.html http://tc.eserver.org/31143.html David Ogilvy was an advertising genius who distilled his successful concepts and techniques into a bestselling book I've just finished reading, called "Confessions of an Advertising Man". I wanted to read his book, because I often find it useful to look at other professions and ask whether their ideas could be applied to the world of technical authoring. http://tc.eserver.org/31115.html http://tc.eserver.org/31115.html Writing documentation isn't merely the act of pounding out dry prose. There is some creativity involved which comes from how you present the information, both textually and visually. The writing, though, needs to be easy to read, complete, concise, and to the point. http://tc.eserver.org/30089.html http://tc.eserver.org/30089.html Although technical documents and mysteries share certain characteristics, emotion separates the two types of writing. Mystery fiction may be popular among technical communicators because it engages both the analytical and the emotive parts of the readers' personality. This panel presentation describes techniques that mystery authors use to trigger readers' emotions. An awareness of these techniques can help technical communicators understand their affection for mysteries and stay clear about the purpose of their own work. http://tc.eserver.org/29127.html http://tc.eserver.org/29127.html Many technical documents present information both graphically and verbally. While much is known about the verbal tools of technical professionals, technical graphics have been less fully examined. Here the drawings of a United States patent are examined revealing a system for organizing and presenting visual information that is analogous to commonly-used models for organizing and presenting verbal information. http://tc.eserver.org/29125.html http://tc.eserver.org/29125.html This article critiques some titles in journal articles for being misleading and it argues that titles need to be informative. Examples are given of work on measuring the effectiveness of titles in two areas--sentence structure and reader comprehension--and the article concludes with brief comments on the effectiveness of book titles. http://tc.eserver.org/29053.html http://tc.eserver.org/29053.html Although rhetoricians have studied the discourse practices of engineers, little is known about the production workers who must assemble engineering knowledge into functional products. This case study examines what happens when a production worker tried to improve manufacturing documentation, and how her success depended upon both her craft knowledge and the rhetorical skills she attributes to a Writing Across the Curriculum program she experienced in college. http://tc.eserver.org/28580.html http://tc.eserver.org/28580.html How can budding writers achieve a middle path in their approach to documentation? This no-model approach is an attempt at busting the myth that only a model-based approach works. http://tc.eserver.org/26474.html http://tc.eserver.org/26474.html Now it is very important to recognize the vital role of a technical writer and services expected to provide to justify the requirements of this profession. Since technical writer is a sub category of technical communication, that involves other categories involved in documentation, like content writer, software configuration manager, technical editor, information designer and many more. http://tc.eserver.org/22598.html http://tc.eserver.org/22598.html Why is my daughter not being taught to read technical literature? Practical things like reading a VCR manual or a pamphlet on health. http://tc.eserver.org/21686.html http://tc.eserver.org/21686.html Technical writers are midwives who deliver the message to users. Experienced technical writers enable you to understand complex technical concepts easily. Based on personal experience, technical writers always put the reader first. http://tc.eserver.org/20321.html http://tc.eserver.org/20321.html Establishing a presence in a department that hasn’t had the benefit of technical writers can pose many challenges. As a writer newly assigned to such a department, I worked closely with my manager to develop the technical writer’s role, presented the role to key staff and teams, and created initial procedures to support writers within the department. By performing these tasks and thinking creatively about handling projects with a limited amount of writers, we’ve been able to work constructively with teams in our department and produce effective documentation. http://tc.eserver.org/19839.html http://tc.eserver.org/19839.html People use documentation differently from what we might expect. They don’t like to read; instead they jump to a task with prior knowledge, and sometimes don’t realize they’ve made an error. Understanding how users learn and applying John Carroll’s minimalist principles will help provide solutions to this problem. Documentation that has been successfully planned and designed for minimalism may take longer to create than other manuals, but reaps the benefits of making users more productive and happy, while reducing support calls, maintenance, translation, and publishing costs. The key factors to a successful minimalist approach (or any good documentation design) are a keen understanding of your users, prototypes designed to match tasks relevant to users, and iterative testing to improve each draft. http://tc.eserver.org/19602.html http://tc.eserver.org/19602.html Looks at usable writing, and convincing the legal department to adopt the tenets of clear writing. http://tc.eserver.org/19159.html http://tc.eserver.org/19159.html The research I discuss in this essay addresses what I take to be an unfortunate imbalance in current research on professional writing. Research reports in journals and in edited collections describe different professional discourses, how they are formed, how they operate, how organizational structure and discourse are related, and how writers learn to participate productively in institutional discourse. With some notable exceptions, very little of the research being reported concerns the ideologically coercive effects of institutional and professional discourse—what my students and I have come to call 'the dark side of the force.' If Foucault had to argue that cultural theorists should think of power as productive rather than merely repressive, I argue that rhetoric needs to recognize that the opposite is also true of discourse. That is, research in professional and nonacademic writing should begin to investigate not only the ways in which discourse produces knowledge, but also the ways in which it extends the grid of discipline and the ways in which writers resist the mute processes to which de Certeau refers in the epigraph above. http://tc.eserver.org/19131.html http://tc.eserver.org/19131.html Though I have a degree in technical communication and have worked as a technical writer for four years, I still had no idea what should be taught in a technical writing classroom, or how one should go about teaching it. Before I ventured into the arena as an instructor, I wanted to find out what goes on in a technical writing classroom. Two types of practical research that I thought would provide some insight into technical writing instruction were: an observation of different technical communication classrooms; and a survey of various textbooks available for technical communication courses. http://tc.eserver.org/18774.html http://tc.eserver.org/18774.html The perils and temptations of high fashion are not unlike those of technical writing. As technical writers, we are bombarded by ever-changing trends. And beyond trends, we must contend with larger movements driven by the digital generation. In the midst of constant change, we are tasked with creating quality material and then shaping it to fresh and exciting designs. http://tc.eserver.org/18692.html http://tc.eserver.org/18692.html This TECHWR-L Magazine section features a selection of quotations from active technical writers about what a day at work looks like. http://tc.eserver.org/15110.html http://tc.eserver.org/15110.html Argues that effective titles and slogans can help members of a documentation team keep their focus while working on a project. http://tc.eserver.org/14026.html http://tc.eserver.org/14026.html Optimism about the future of technical writing can be sustained only if we persist in setting for technical writing the same standards we apply to other sophisticated modes of writing and require refinement in style as well as accuracy in content. The importance of content in technical writing, of the information presented, may seduce us into seeing technical writing as purely a form of language engineering and into teaching our students to perform mechanical writing tasks, churning out dull reports to fit mindlessly into the institutional norms of industry and government. http://tc.eserver.org/14000.html http://tc.eserver.org/14000.html One indication of the state of our profession is the discriminations that we are just getting around to making: useful, even essential, 'sortings out' that, when then, are made, seem embarrassingly obvious. One such 'sorting out' or discrimination is essential for an understanding of what any composition class can do, whether advanced composition, technical writing, feature writing, or whatever. In the writer’s repertoire, there are local and transferable skills. Local skills have to do with a given genre and involve such matters as special forms (e. g., the scientific report), footnoting, vocabularies, special styles, and even the 'tones' that particular fields demand. Transferable skills are the 'basics' of writing: syntactic fluency, control of diction, sense of audience, organizational ability, 'mechanics' such as punctuation and spelling. http://tc.eserver.org/13978.html http://tc.eserver.org/13978.html Janet Emig's 1971 study, The Composing Process of Twelfth Graders, spurred an interest in the writing process: how writers compose rather than simply what they compose. However, a survey of current literature indicates that little has been published on the composing processes of technical writers. Perhaps we have assumed that technical writers compose as other writers do. In order to test this assumption, we conducted the research on which we base this study. http://tc.eserver.org/13840.html http://tc.eserver.org/13840.html This article examines the critical perspective as an alternative to our current descriptive, explanatory research focus. The critical perspective aims at empowerment and emancipation. It reinterprets the relationship between researcher and participants as one of collaboration, where participants define research questions that matter to them and where social action is the desired goal. Examples of critical research include feminist, radical educational, and participatory action research. Adopting the critical perspective would require that scholars in professional communication rethink their choices of research questions and sites, their views of the ownership of research results, and the types of funding they seek for research initiatives. http://tc.eserver.org/10426.html http://tc.eserver.org/10426.html This article contributes two arguments to the disciplinary conversation of technical communication with the aim of exploring leadership opportunities our field has in the field of information technology. The arguments assert that 1.) Writing is the core technology in any IT system, and all IT systems attempt to leverage the core strengths of writing to make these systems more valuable. 2.) Technical communicators have a central role to play in IT systems consonant with our core competencies: we attend to the balance of situated as opposed to generalized strategies and the balance of appeals to identity in writing about the practical use of technology, and we are well prepared to attend to these balances in other important arenas of IT discourse. Together, these two arguments are meant to begin or continue conversations—in workplace and academic contexts alike—that bring the issues of IT development and the future of technical communication closely together.