http://tc.eserver.org/dir/Writing A listing of the most recently indexed works about 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/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/35803.html http://tc.eserver.org/35803.html Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment. http://tc.eserver.org/35804.html http://tc.eserver.org/35804.html I’m working on a project to boil a 150-page software user document down to a one-page reference guide that can be tacked to a CSR’s cube wall. Our goal with the one-page reference guide is to give the CSR a description of all the navigation elements and application functionality so they can quickly navigate to where they want to go without first having to trudge through the complete 150-page user doc. http://tc.eserver.org/35807.html http://tc.eserver.org/35807.html Do you know if you're promoting features or benefits in your marketing materials? The answer to this question plays a significant role in the effectiveness of your marketing message. While features are facts benefits explain why facts are important. Its these benefits that target your prospects emotions a key factor in selling situations. http://tc.eserver.org/35810.html http://tc.eserver.org/35810.html Technical writing is a position that requires a lot more than just writing. The ability to collaborate and coordinate is key and in actuality, only about 30 percent of your time is spent writing. The responsibilities of a technical writer includes constant contact with others. Job duties range from writing internal technical documents, writing and editing manuals, producing online tutorials, and in some cases, even web-based training programs. http://tc.eserver.org/35825.html http://tc.eserver.org/35825.html While style guidelines can be useful for maintaining consistency across a set (or several sets) of documentation, the editors that I worked with viewed the style guidelines as sacrosanct. Any deviation, no matter how small, was punishable by a nasty email and a sharply worded note to the offending writer’s manager. http://tc.eserver.org/35801.html http://tc.eserver.org/35801.html Single-source publishing is a zombie idea that revives itself periodically and refuses to stay dead. Its zombie supporters chant its purported benefits as a “write once, publish to many” promise and ploddingly follow it as their ultimate goal for mechanized authoring and machine translation. As an object-oriented writing methodology, it is as human as present-day robot technology—good only for conveyor belt assembly or specialized tasks, and always very expensive to implement. Single-source publishing lacks purpose in today’s world of information turnover and the dynamic nature of the Web 2.0 moving to Web 3.0 landscape. http://tc.eserver.org/35781.html http://tc.eserver.org/35781.html Writing in a more conversational tone is a worthwhile goal. If you do it properly, you can draw readers in and make them more comfortable. The keys are to write as you'd speak, and to keep the flow and cadence smooth. http://tc.eserver.org/35782.html http://tc.eserver.org/35782.html A report of a presentation by Dru Lavigne at FSOSS 2009 that discussed how to create and sustain a writing career by writing about Open Source. http://tc.eserver.org/35786.html http://tc.eserver.org/35786.html Writing quickly is a skill that you should definitely cultivate. This blog post looks at four techniques that you can use when you need to write quickly. http://tc.eserver.org/35787.html http://tc.eserver.org/35787.html Structure is a key component to anything that you write. In this blog post, Scott Nesbitt discusses the importance of structure in the context of using the LaTeX typesetting language. 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/35743.html http://tc.eserver.org/35743.html I was disappointed yesterday when, while cruising Facebook, I noticed a national pharmacy company’s request for me to “fan” them. I simply cannot agree to become a fan of a company that thinks turning nouns into verbs is hip and thereby will increase its customer base. If they had instead asked me to “become a fan”, I may have indeed considered it. http://tc.eserver.org/35745.html http://tc.eserver.org/35745.html What is flow? It’s kind of like a river of writing, it’s an uninterrupted stream of consciousness directly from the source of your creativity through your brain, into your nervous system, out your hands, into your computer. I like to think of it as zen writing meditation. There is some important prep work that needs to be done before you’re ready for some serious writing flow time. http://tc.eserver.org/35746.html http://tc.eserver.org/35746.html Are you prone to digital fiddling? I am. In fact, I’ve increased my skills of digital fiddling so much that I hardly notice that I’m putting off writing. There are three actions you need to take. http://tc.eserver.org/35747.html http://tc.eserver.org/35747.html A large number of us want people to be able to share ideas and communicate freely, without legal restrictions. And I’d go even further: we like it when creative people freely share their work with us, and allow us to use their work (or derivatives of it) in our own work. This is the Culture of Sharing that is growing on the Internet. http://tc.eserver.org/35748.html http://tc.eserver.org/35748.html I find it unbelievable that a common phrase (that was used way before it was the title of any book) can be trademarked. We’re not talking about the names of products … we’re talking about the English language. You know, the words many of us use for such things as … talking, and writing, and general communication? Perhaps I’m a little behind the times, but is it really possible to claim whole chunks of the language, and force people to get permission to use the language, just in everyday speech? http://tc.eserver.org/35750.html http://tc.eserver.org/35750.html One of the most common pieces of advice for bloggers is to find a niche that you can dominate — the smaller the niche, the better, because all of the bigger niches are already dominated by bigger blogs. This advice is fine if you’re trying to sell a product to a specific group of potential customers, but if you’re trying to grow a blog with as big a readership as possible, I think niche blogging is dead wrong. http://tc.eserver.org/35751.html http://tc.eserver.org/35751.html Writers like to sprinkle their work with subordinate clauses because they add variety to sentence structure. A reading diet too heavy with simple sentences or even compound sentences becomes wearisome quickly. Subordinate clauses—also known as dependent clauses—used skillfully can add complexity and artfulness to writing. http://tc.eserver.org/35716.html http://tc.eserver.org/35716.html Editing really is a wonder– it’s like a multiplication of the writer’s brain, a dialogue among various copies of the author. First-draft author is an admirable workman but a bit of a hack; he writes down whatever pops into his head. Second-draft author is slower-paced but has a clearer eye for how the larger story structure fits together, or at least how it should fit once he’s done with it. Third-draft author has a remarkable knack for turning familiar and overused phrases into fresh, surprising stuff, by masticating each line. And so on. All these guys team up to make something great, and none of them could have done it alone. http://tc.eserver.org/35719.html http://tc.eserver.org/35719.html Most technical writers see outsourcing as a real threat. But, if you look at it from another angle, it’s one huge business opportunity. http://tc.eserver.org/35720.html http://tc.eserver.org/35720.html Maybe I’ve been very lucky but I believe women are far better as technical writers than men. Here are five areas where I think they have the edge of the guys. http://tc.eserver.org/35708.html http://tc.eserver.org/35708.html Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation. http://tc.eserver.org/35709.html http://tc.eserver.org/35709.html Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation. So how do you learn to write (anything) well? There’s only one answer: you’ll learn to write well if you write. A lot. http://tc.eserver.org/35710.html http://tc.eserver.org/35710.html All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass. If you really want to produce great documentation, it needs to be edited. http://tc.eserver.org/35714.html http://tc.eserver.org/35714.html The point of a quick-start guide is, as the name says, to help the users get on their feet as fast as possible. This requires the writer to ask, “What is the absolute minimum that someone needs in order to get started?” The next best question is “What is the user going to do the most often?” http://tc.eserver.org/35625.html http://tc.eserver.org/35625.html Janet Swisher, who’s worked in technical communication since 1999, is an Information Developer for a medium-sized software company. Her specialist areas include online help, tutorials, API documentation and programmer guides. My “techie” cred is that she “can read code well enough to avoid asking obvious questions, and write code well enough to be dangerous.” http://tc.eserver.org/35629.html http://tc.eserver.org/35629.html On the web, write in small digestible chucks, which fit into the information hierarchy. To create your hierarchy, outline the website as you would for printed material. Then examine the site’s purpose and outline the main sections (e.g. words people use to navigate) and the links within those heads. Test it before it goes online. http://tc.eserver.org/35630.html http://tc.eserver.org/35630.html Jane R. in Texas asks for some tips on interviewing tech writers, especially when using assessment tests. Her company is about to hire their first full-time writer and they have not done this before. I’ve worked on both sides on the fence in the past, (i.e. interviewed and been interviewed) and picked up a few tings in the process. Hopefully, these will be of some help. http://tc.eserver.org/35634.html http://tc.eserver.org/35634.html The procedure I wrote about creating a Twitter list uses abbreviated content. This post describes the reasoning behind and decisions made in writing the topic. http://tc.eserver.org/35680.html http://tc.eserver.org/35680.html Although the creation and translation of technical documents are essential parts of the product lifecycle they still play a subordinate role in most international organizations. Many companies are therefore leaving these tasks to an outsourcing provider. To ensure a smooth collaboration and guarantee high quality technical documents, the outsourcing process needs to be planned and supported thoroughly. http://tc.eserver.org/35683.html http://tc.eserver.org/35683.html Working with people from around the globe has become common practice for both authoring teams and technical documentation professionals. A recent survey conducted by SDL investigated the development of global authoring. The results were compared to surveys from 2007 and 2006. They reveal trends in working methods and shed light on the effects of globalization on global authoring. http://tc.eserver.org/35605.html http://tc.eserver.org/35605.html I like the concept of not treating the readers of documentation like idiots. This little card gave me the information that I needed and couldn’t know ahead of time (how much water to use, the filter looks too big but is the right size, only push the button once) without wasting my time by giving me information that I either already knew or could easily guess (I can get water from the sink, I need to use a cup). Can we use this concept in software documentation? What parts can safely be left out so that we are only highlighting the pieces that are really needed? http://tc.eserver.org/35585.html http://tc.eserver.org/35585.html When you set yourself up as a grammar expert it's better than being an expert on plastics. To be an expert on plastics you actually have to know something about plastics. With grammar the analogous thing doesn't hold. Nobody asks, nobody checks, nobody knows enough to get suspicious. You are free as a bird to publish any garbage you might want to type out. http://tc.eserver.org/35586.html http://tc.eserver.org/35586.html One common complaint a lot of technical writers have is that they aren’t included early enough in lifecycle of a project. The downsides are that by the time work hits your desk you don’t have a full picture of who the customer is, why they want whatever it is you are building, and how they want it provided to them. All of which directly impacts the information being created. http://tc.eserver.org/35587.html http://tc.eserver.org/35587.html The basic sentence in English is noun-verb-object: The player hit the ball. But we seldom leave it at that. We add things on the front. We add things on the back. We interrupt the sentence to say something else, and then come back to the sentence. We vary the basic sentence structure. And, in the most extreme cases, we substitute other things for the noun, the verb, and the object. All of this gives us great flexibility in creating sentences, but this very flexibility leads us to the problem of which variation to choose, and why. http://tc.eserver.org/35589.html http://tc.eserver.org/35589.html The life of a Technical Writer is far from boring. Days spent typing away at a keyboard are often disturbed by the rigours of the corporate world. I was reminded of this earlier today when one of my team, a relatively new recruit to the world of technical authoring, discovered that occasionally being kept in the dark can be annoying. In honour of this momentous occasion, I offer to you for your delectation my own top ten ways to annoy a Technical Author. http://tc.eserver.org/35535.html http://tc.eserver.org/35535.html Is less always more? I’m not sure. But if Apple’s minimalistic designs are any indicator of trends, minimalism in documentation is something to pay attention to. Here are five ideas for minimizing documentation. http://tc.eserver.org/35536.html http://tc.eserver.org/35536.html I was preparing a report on freelance technical writers and noticed how hard it was to find technical writing sites run by writers, most were recruitment site. So I’ve made a list of the top 50 technical writers with a web presence. Some of these you might know, such as Darren Barefoot and Tom Johnson. I have also added some other writers from India, Russia and Israel to reach out to a wider audience. http://tc.eserver.org/35541.html http://tc.eserver.org/35541.html There are no rules or absolutes in finding a tech writer. For example, I look for the following when hiring a candidate. http://tc.eserver.org/35542.html http://tc.eserver.org/35542.html Nobody graduates from high school and says, I want to grow up and become a tech writer. http://tc.eserver.org/35543.html http://tc.eserver.org/35543.html Technical writing is the process of taking very technical information and processing it so a larger group of readers can understand. This involves strong writing skills, understanding the technical inputs and a creative way to display this information for the reader. http://tc.eserver.org/35544.html http://tc.eserver.org/35544.html The technical writing process consists of four main phases. These are planning, writing, delivery, archiving. These phases are not necessarily set in stone and some variations do exist. Every writer is different and they each have their own way of writing that is distinct. http://tc.eserver.org/35545.html http://tc.eserver.org/35545.html The technical writing process consists of four main phases. These are planning, writing, delivery, archiving. These phases are not necessarily set in stone and some variations do exist. Every writer is different and they each have their own way of writing that is distinct. http://tc.eserver.org/35546.html http://tc.eserver.org/35546.html Many organizations produce in-house tools or modify commercially-available tools for their own use. These tools should get documented so they are of use to others in the organization. If this documentation is not created or is poorly written, it costs you twice. http://tc.eserver.org/35512.html http://tc.eserver.org/35512.html I have never fabricated or fictionalized research data. Besides being completely unethical, that would have missed the point. It would have taken all the fun out of it! How easy and how boring that would have been. http://tc.eserver.org/35517.html http://tc.eserver.org/35517.html “Know your audience” is a standard rule of writing, and Henning shows how that applies to technical communicators. By looking at your project from the point of view of the end user, Henning illustrates, you can provide a better document and improve your company’s bottom line as well. http://tc.eserver.org/35518.html http://tc.eserver.org/35518.html Bette Frick and Betsy Frick discuss how a style manual can save time and money, how to select the proper style manual and get buy-in, and how to create a style guide to use in conjunction with a style manual. http://tc.eserver.org/35522.html http://tc.eserver.org/35522.html Diane Wylie is not only a technical writer but also a writer of historical romance novels. Read how the two types of writing compare and how they differ. http://tc.eserver.org/35526.html http://tc.eserver.org/35526.html I have been remiss at writing new content for this blog, and whilst this topic isn’t one that I said I’d post about (those posts are coming, I promise), it’s something I was discussing yesterday and so is at the forefront of my mind. Like many people I still use pen and paper when taking notes, and regardless of the type of meeting I stick with three basic categories. 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/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/35496.html http://tc.eserver.org/35496.html A clear, well-illustrated guide to when one should (or should not) use an apostrophe. http://tc.eserver.org/35470.html http://tc.eserver.org/35470.html We are all going to have to collaborate like never before. Everyone should select at least one area of interest and specialize as best they can. Then we will need to start meeting and sharing information. Immediately. There are several ways to do this, I believe. http://tc.eserver.org/35471.html http://tc.eserver.org/35471.html Doc whisperers are more commonly known as "senior technical writers", but what's in a name anyway? So if you want to be a great tech writer—start whispering. http://tc.eserver.org/35472.html http://tc.eserver.org/35472.html White papers are a fundamental part of your marketing arsenal. And if you think technical writers don't need to worry about marketing, read on to see why white paper writing is an essential skill, and how to turn a ho-hum paper into a killer communications tool. http://tc.eserver.org/35467.html http://tc.eserver.org/35467.html Most writers do not set out to go into this field, but more likely happen into it by chance or by a series of stepping stones that naturally led them down this path. I stated that through nature and nurture, people are formed to become a writer. So, what characteristics make up your average writer? http://tc.eserver.org/35415.html http://tc.eserver.org/35415.html You are a high-tech/Bio-tech company and your first product is nearing release. The product requires documentation and you ask your self what are our options? Before deciding you should consider these factors. http://tc.eserver.org/35424.html http://tc.eserver.org/35424.html Optimizing the translation process has two basic components: improving the writers' source texts and improving the translators' process. For the moment, we'll focus on the writer's job. Dear Translator: Please remember that most writers never had any training at all about translation and usually know one lonely language. Many of them can only rely on the limited writing advice that they got in school. They're never aware of how they can make life hellish for translators and for international readers. So, don't blame them; help them out. Pass this list on to them and discuss it until they understand. http://tc.eserver.org/35409.html http://tc.eserver.org/35409.html Observations about freelance technical writing in Israel. http://tc.eserver.org/35408.html http://tc.eserver.org/35408.html Write technical materials, such as equipment manuals, appendices, or operating and maintenance instructions. May assist in layout work. Industries with the highest published employment and wages for this occupation are provided. For a list of all industries with employment in this occupation, see the Create Customized Tables function. http://tc.eserver.org/35385.html http://tc.eserver.org/35385.html As you blog, remember that you have a relationship with your readers -- a relationship that requires you to disclose any important information, especially monetary, that might bias your views. Don't ruin relationships with those around you by revealing private details of their lives without approval. Ensure you don't represent your company in a negative light. And choose balanced, honest posts rather than sensationalism. http://tc.eserver.org/35379.html http://tc.eserver.org/35379.html The impending launch of Google Wave is something for every technical writer to watch. Because if they have been doing their job the same way from day one, then Google Wave's undertow is going to pull them down into the surf. However, if they are embracing online collaborations tools, instant messaging, and related technologies then they are going to think Google Wave is game changer for technical communications because it offers a new range of communications and collaborations options. http://tc.eserver.org/35369.html http://tc.eserver.org/35369.html We confuse people when there is a disconnect between our stated beliefs and our theories in use. When managers say they demand teamwork but evaluate employees based on individual accomplishments, they do a disservice to the person who puts the team's overall needs ahead of his or her specific goals. That person gets punished for believing what the boss said and acting on it. But don't be so quick to blame the disconnect on your behavior--It could be you are reciting scripts that describe what you think you should do. http://tc.eserver.org/35375.html http://tc.eserver.org/35375.html There are at least two broad categories of technology that managers often confuse. The first is technology that replaces a particular skill. For example, the cash register at a McDonalds has technology that relieves cashiers from doing math, so they can hire people who are not skilled in math. The second is technology that allows a skilled practitioner to be more productive. For example, the computer makes it possible to write and edit text much more easily than a typewriter, but it won’t make a bad writer better. http://tc.eserver.org/35358.html http://tc.eserver.org/35358.html Describes the most challenging aspect of creating slides for an oral presentation. Presents two principles for creating informative and persuasive graphics. Explains how to use drawing tools to communicate the schema of the slide and to emphasize important portions of the images. http://tc.eserver.org/35321.html http://tc.eserver.org/35321.html One page or separate pages? When faced with that decision, ask yourself these questions: How much do people want in one visit? How connected is the information? Am I overloading my site visitors? How long is the web page? What’s the download time? Will people want to print? How much will they want to print? http://tc.eserver.org/35326.html http://tc.eserver.org/35326.html Although getting a job is the focus of the podcast, I also talk about what technical writers do, how they approach a project, how they decide what to create, and how they generate ideas for tasks. Specifically, I talk about about a project people can work on at tech.lds.org. People can start writing help for the project here. http://tc.eserver.org/35328.html http://tc.eserver.org/35328.html I worked as a technical writer many years ago and then quit to take care of my kids. Now I'd like to get back into the field. How do I get my foot in the door when all employers require experience? http://tc.eserver.org/35309.html http://tc.eserver.org/35309.html Being boring is sin #3 in my list of the seven deadly sins (which include being fake, irrelevant, boring, unreadable, irresponsible, inaccessible, and inattentive). Perhaps a more tactful way of saying something is boring is to say the writer neglects to “keep the audience’s attention.” http://tc.eserver.org/35296.html http://tc.eserver.org/35296.html Technical writers write technical materials, such as equipment manuals, online help documentation, operating directions and maintenance instructions. Rank: 28th best job in America. http://tc.eserver.org/35297.html http://tc.eserver.org/35297.html A Content Curator is someone who continually finds, groups, organizes and shares the best and most relevant content on a specific issue online. I think that professional writers and technical writers should consider a move towards this role. We already search for and find the best content, sift through loads of content, discard poor content, and publish the most worthy content whenever a software release goes out. This description also sounds like something a content strategist would do as part of their analysis of the content. http://tc.eserver.org/35285.html http://tc.eserver.org/35285.html When the subjects of usability and user friendliness in relation to documentation are broached, writing isn’t often the first thing that comes to mind. But it should be. http://tc.eserver.org/35290.html http://tc.eserver.org/35290.html Those within technical communications have long argued that product documentation provides significant value in terms of a customer satisfaction and downstream savings in customer support and service. In the broader, enterprise perspective, however, documentation is generally viewed as simply one of many requirements for product launch. This perspective is often the result of the lack of visibility that is generally available into the business value contributed by product documentation. Aberdeen investigated and isolated the quantifiable business impact of technical communications makes for 165 participating companies. An analysis of this data indicates that when leveraged effectively, technical communications stands to contribute as much as a 42% increase in customer satisfaction and an associated 45% increase in product revenue. This report provides a quantified framework for understanding the potential impact on technical communications makes for business profitability as well as the best practices to adopt to drive greater value from this organization. http://tc.eserver.org/35279.html http://tc.eserver.org/35279.html My concern for US writers is that they fail to grasp the momentum that counties like India have established and the high quality of university graduates they are now producing. In the next 10-15 years, IT jobs which can be replicated offshore/offsite to lower costs will be embraced more aggressively. US companies have little choice but to do this. http://tc.eserver.org/35280.html http://tc.eserver.org/35280.html Documents fail for many reasons. One common mistake is to adopt a ‘one size fits all’ approach to your audience. This works only when generic material, usually of a non-technical nature. http://tc.eserver.org/35281.html http://tc.eserver.org/35281.html These points are not meant to be all-inclusive. However, if you are new to tech writing, this should put you on the right road. http://tc.eserver.org/35277.html http://tc.eserver.org/35277.html Changes are so massive, so fast, and coming from so many directions that it is impossible to keep up. Still, it’s important to try. For anything that applies to IT applies to tech writing. Writers must be know something about everything and be ready for it. We’re going to have to specialize and collaborate more than ever before. http://tc.eserver.org/35258.html http://tc.eserver.org/35258.html This article examines the phenomenon of blogging as a way to create a cybernetic space that is defined by the digital/virtual space of the blog discourse and the real space where the blogger is located. By examining several blogs it is argued that for people who have to move from place to place and undergo the diasporic experience, the anxieties of movement and placelessness produced by diaspora can be partly managed by entry into the cybernetic space produced by bloggers. Specifically, this article examines blogs maintained by people of Indian origin who produce a sense of spatial identity through their blogs. http://tc.eserver.org/35219.html http://tc.eserver.org/35219.html In reality, the user just wants a brief, clear explanation of a concept or task. The user will glance and skim — reading behaviors hardly worthy of the elitist grammarian who argues the finer points of “which” versus “that” in restrictive clauses. http://tc.eserver.org/35220.html http://tc.eserver.org/35220.html For companies that are struggling in the current times because of the economic slowdown, an option that might not compromise on product quality is to switch to open-source software. In this article, I will talk about open-source publishing tools for the writing community. http://tc.eserver.org/35221.html http://tc.eserver.org/35221.html I learnt that a verb is the most essential part of speech. So, I thought investing a little time to learn to use it better (if not master it) might not be a bad idea. But then, there are so many aspects of a verb. Can I ever say I learnt it? I can try one proven (presumably by the British) method: divide and conquer. I will start with the voice of a verb, the much-talked-about aspect of a verb. http://tc.eserver.org/35222.html http://tc.eserver.org/35222.html One of the difficult concepts to understand in the English language is perhaps the manner in which articles are used in a sentence. Over the course of one's life history, every student of English has had to face this nightmare at one point of time or another. The verbs are all in place and you know the nouns, the pronouns are fairly obvious, and the prepositions can eventually be worked out, but what comes before the word year and what comes before SMS is tricky. http://tc.eserver.org/35223.html http://tc.eserver.org/35223.html Like most people who entered the technical communication profession in India in the mid to late 1990s, I too became a technical writer more by accident than by design. I enjoyed my technical writing career thoroughly, but slowly moved away, and a decade later, I now find myself heading the Quality Management function at a multi-national clinical research and technology company in India. The career paths of no two individuals are similar. And yet, there are always some common themes in successful transitions from one career path to another. http://tc.eserver.org/35224.html http://tc.eserver.org/35224.html If you are reading this article in INDUS, I assume that the majority of you must be technical writers. The peer-review checklist might be firmly etched in your mind. Please make sure this checklist in disabled. If doing so is not possible, just click the X sign at the top-right corner of the screen. Also, if you have no sense of humor, it is mandatory to click the X sign. I make no apologies for the grammatical errors or syntax errors or sentence structure or comma splices or… whew..pant..pant… this ‘or’ is making me breathless. In fact, I am thriving on these errors because my creative skills are running riot. I have expressed my thoughts in an unconventional manner and, believe me, the feeling is exhilarating and invigorating. http://tc.eserver.org/35208.html http://tc.eserver.org/35208.html In such a scenario, this article presents some of the practices that have helped me track and address inputs effectively – regardless of their volume and importance. http://tc.eserver.org/35211.html http://tc.eserver.org/35211.html Style guides recommend certain styles. In the domain of technical communication, we refer to guides for writing style, presentation of content in user documentation and technical documents, and graphical user interface of software and web sites. http://tc.eserver.org/35159.html http://tc.eserver.org/35159.html There's no point in having an awesome website and an awesome product if your product comparison table is crap. It will throw people right off, and believe me I have seen some bad tables. Anyway here is a collection of the best product comparison tables handpicked by WebdesignDev. We think we have picked the top 25 comparison tables based on creative design and how clear it is to read and compare. http://tc.eserver.org/35129.html http://tc.eserver.org/35129.html This article documents a novel yet theory-informed process of preparing research reports designed for government officials who are concerned with creating adult-literacy policy. The authors use cartoons that include verbatim dialogue from the transcripts of interviews with research participants with low functional literacy. This dialogue, which depicts positive messages about the participants’ moral character, strengths, and resilience, is set against photographic backdrops of the participants’ lived environment to give a sense of real people in a real place. Inclusion of such images is an attempt to change policy-report readers’ thinking about adult literacy because creative visual communication offers ways to approach this challenge that text alone cannot. http://tc.eserver.org/35132.html http://tc.eserver.org/35132.html Rensselaer’s Technical Writers' Institute, the first program of its kind, had a profound impact on technical communication. It enabled technical communicators without formal education in the field to gain important knowledge, provided a forum for communicators from different industries to meet in order to solve mutual problems, played a key role in defining the field and its needs, encouraged recruitment (including the hiring of more women), promoted professional societies and formal degree programs, and seriously affected industry training programs by enabling them to use institute teaching materials. Knowledge gained through the Technical Writers' Institute enabled Rensselaer to develop many other innovations. http://tc.eserver.org/35138.html http://tc.eserver.org/35138.html In working with business executives, engineers, and government officials to improve their writing, I learned that it is much easier to teach clarity than tone. To bolster lessons on tone, I now draw on theory and research from interpersonal communication and social psychology. In the following discussion, I describe one such approach: applying the concept of defensiveness to business and technical writing. http://tc.eserver.org/35148.html http://tc.eserver.org/35148.html If you’re a college student looking to become a technical writer after you graduate, you face a formidable challenge: you can’t get a job without experience, and you can’t get experience without a job. Especially in a competitive job market, getting a job as a technical writer directly after you graduate — without a foundation of previous jobs, experience with a handful of tools, and an impressive portfolio — can be especially difficult. However, if you follow these seven steps, which are not easy, not something you can do overnight, you will find a job. http://tc.eserver.org/35125.html http://tc.eserver.org/35125.html I’m advocating boiling the documentation down to the essentials. Remove any superfluous material. Tell the user how to do things with a piece of software or a gadget, not what that something can do. You might wind up with documentation that’s just a set of procedures connected together by linking material and cross references. Don’t bog them down with what’s not necessary for them to get things done in a fast and efficient way. http://tc.eserver.org/35126.html http://tc.eserver.org/35126.html This Authors’ Guide tells you everything you need to know to write Missing Manual. It starts out by giving you a brief introduction to the Missing Manual way of explaining things and then takes you through the nitty gritty of style guidelines, figure formatting, and so on. http://tc.eserver.org/35127.html http://tc.eserver.org/35127.html The purpose of my blog is to provide tech writers with information about changes and how said changes may impact documentation. That is also the purpose of my Twitter feed. I gather up as much information as I can and pass it on. I've found some excellent feeds to follow related to the various topics of which tech writers need to be aware. http://tc.eserver.org/35120.html http://tc.eserver.org/35120.html An organized kit of technical-writing exercises, guidelines, activities, and strategies refined and tested in real high-school classes, with notes and comparisons to help teachers borrow and adapt them. Also used for teacher professional development at the Edward Teller Education Center. http://tc.eserver.org/35121.html http://tc.eserver.org/35121.html The value of learning effective nonfiction nonnarrative writing ("technical writing") for middle- and high-school students has been cited repeatedly in official and unofficial academic standards starting in the early 1990s. 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/35114.html http://tc.eserver.org/35114.html A description of Andrea Lunsford's argument, from research with the Stanford Study of Writing, that technology isn't killing our ability to write. It's reviving it—and pushing our literacy in bold new directions. http://tc.eserver.org/35116.html http://tc.eserver.org/35116.html Technical writers love the written word. Perhaps, we love it a little too much? We need to ask ourselves is the written word the best thing for documentation? Is it the best thing for us as an industry, and is it the best thing for you as a content developer. http://tc.eserver.org/35094.html http://tc.eserver.org/35094.html Designers believe that if something isn’t working well, and it comes down to changing the copy or the design, it’s always the copy that should be changed, reduced or sometimes nearly completely eliminated. How can I convince my designer co-workers that succinct, simple and memorable words can be just as important as the visuals? http://tc.eserver.org/35090.html http://tc.eserver.org/35090.html Be vicious when you edit. Vicious. Follow these recommendations with zealous fervor. They help your writing say what it should in a way we’ll understand. http://tc.eserver.org/35091.html http://tc.eserver.org/35091.html How exciting is technical writing, really?” Every once in a while, discussions in blogs or at conferences turn to that question. How technical writing is not really a calling or maybe even boring. Technical writing is my creative passion. I don’t have a recipe, but I want to share my excitement. Maybe it resonates with you, and maybe you’ll see technical writing in a different way. http://tc.eserver.org/35086.html http://tc.eserver.org/35086.html Most people consider writing to be a creative endeavor, and in some situations, it certainly is. But creativity is not just associated with writing, art, and the humanities. Penelope Trunk broadens creativity to include problem solving too. http://tc.eserver.org/35087.html http://tc.eserver.org/35087.html While the content of what I write at work is not all that interesting, and even the paradoxes or other conundrums about technical writing sometimes dull, I really get excited about the technology side of my job. New technologies are emerging each day at a rapid rate. It’s like we’re living in the internet era before the dot.com burst. This is a Web 2.0 land, where even Google threatens to become the next operating system. I am really eager to use a wiki to write my next set of documentation. http://tc.eserver.org/35055.html http://tc.eserver.org/35055.html Here are two main methods you can use to launch off your article marketing campaign. http://tc.eserver.org/35078.html http://tc.eserver.org/35078.html It is our position that use of PowerPoint for document planning negatively impacts all potential collaborative authoring and review outcomes. Though PowerPoint is commonly used because it is a familiar tool, it is not the most effective tool for managing knowledge either intellectually or financially. http://tc.eserver.org/35079.html http://tc.eserver.org/35079.html One of the big problems in document review is that reviewers often fail to recognize that their principal job as a reviewer is to act as a surrogate for the document end-user, in this case the regulatory reader. In this article, we offer a characterization of the reading style of the regulatory reader which is useful to keep in mind when reviewing any document or group of documents to be submitted to pharmaceutical and medical device regulatory agencies. http://tc.eserver.org/35028.html http://tc.eserver.org/35028.html Take the definite article. Please. The editors at SAS continue to struggle with the question of which SAS product names require the definite article and which require the zero article (linguist-speak for no article at all). http://tc.eserver.org/35026.html http://tc.eserver.org/35026.html The health care reform bill now under consideration in the House of Representatives includes a proposal that certain disclosures in insurance policies be made in “plain language.” Another piece of legislation now being considered by both houses of Congress would likewise require uniform and simplified coverage information, much like what’s required on nutritional labels. These are excellent proposals, but they do not go far enough. Plain-language disclosures of some policy information and consumer-friendly labels are no substitutes for making an entire policy readable. http://tc.eserver.org/35024.html http://tc.eserver.org/35024.html Minimalism is something people might strive for, but they don’t know where to start. http://tc.eserver.org/35015.html http://tc.eserver.org/35015.html There's a shift happening in the way in which documentation is produced. We’ve all seen the beginning of it: the growing volume of what’s called (among other things) user generated or crowdsourced documentation. That trend is growing. And while a number of people in our profession are still resistant to the idea, it’s only a matter of time before users are our main partners in creating documentation. http://tc.eserver.org/34983.html http://tc.eserver.org/34983.html You can avoid adverbs most of the time by cutting them out -- the reader can do just fine without the extra information. http://tc.eserver.org/34986.html http://tc.eserver.org/34986.html This research article reports the results of an online survey distributed among technical writing instructors in 2006. The survey aimed to examine how we teach intercultural communication in basic technical writing courses: our current practices and methods. The article discusses three major challenges that instructors may face when teaching about intercultural communication. These challenges concern teacher preparation, time and proposed goals and objectives, and teaching materials and methods. This article provides some suggestions for addressing the challenges and enriching a technical writing curriculum. http://tc.eserver.org/34990.html http://tc.eserver.org/34990.html Many authors give advice to students about how to write the Introduction section of their articles. Some give examples of different ways of doing this in general, and a few discuss the opening sentence in particular. In this article, 13 different types of opening sentences are outlined, and their usage contrasted in British and American journals in the Sciences and Social Sciences. Implications for teaching are considered. http://tc.eserver.org/34998.html http://tc.eserver.org/34998.html This article investigates the status of orality in the history of technical communication. The article calls for orality as an integral part and driving force of technical writing. The article brings to light the misconceptions that have led to a diminished role of oral communication in technical writing. The article shows the implications of oral skills for improved effectiveness of technical communicators. The article outlines the challenges and promises of teaching oral communication in technical writing. http://tc.eserver.org/35004.html http://tc.eserver.org/35004.html A significant problem for practitioners of technical communication is to gain the skills to compete in a global, multicultural work environment. Instructors of technical communication can provide future practitioners with the tools to compete and excel in this global environment by introducing heuristics of cultural dimensions into the service-level classroom. By practicing how to use these heuristics in "real-world" contexts, instructors can prepare students to function as both information architects and symbolic-analytic operators within this global work environment. In this article, I first examine common cultural heuristics as they pertain to business communication. Next, I articulate how technical communicators can benefit from incorporating these heuristics into the classroom. Finally, I offer a pedagogical approach to introducing heuristics of cultural dimensions into the service-level technical communication classroom. http://tc.eserver.org/34977.html http://tc.eserver.org/34977.html For the freelance writer on the go, there are some items that are essential for what they're doing. This post looks at the gear that one writer uses when working away from the home office. http://tc.eserver.org/34978.html http://tc.eserver.org/34978.html Writing tightly means packing the most information into the least amount of space. It's not easy, but when you do it, the result is like magic. The key to being an effective writer is to keep what you’re writing short, to the point, and easy to read. Like the best writing on the Web. 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/34919.html http://tc.eserver.org/34919.html The traditional distinction between writing across the curriculum and writing in the disciplines (WID) as writing to learn versus learning to write understates WID's focus on learning in the disciplines. Advocates of WID have described learning as socialization, but little research addresses how writing disciplinary discourses in disciplinary settings encourages socialization into the disciplines. Data from interviews with students who wrote lab reports in a biology lab suggest five ways in which writing promotes learning in scientific disciplines. Drawing on theories of situated learning, the authors argue that apprenticeship genres can encourage socialization into disciplinary communities. http://tc.eserver.org/34920.html http://tc.eserver.org/34920.html Research suggests that book reviews in academic journals tend to be positive but that readers prefer book reviews that include negative and positive evaluation. In this study, the author examines 48 books reviews from three business communication journals to determine whether these reviews are mainly positive. She counts compliments and criticisms, analyzing their location and topics. She also analyzes the force of the criticisms and strategies that reviewers use to mitigate criticism. http://tc.eserver.org/34913.html http://tc.eserver.org/34913.html How do you get fresh blog content even if you want a break, say a summer off of the routine of writing two posts a week? In this guest post, Anne Gentle discusses just that. The short answer? By tapping into your community or writing ahead. 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/34905.html http://tc.eserver.org/34905.html リンクの最初の11文字がどれだけ理解されるかをテストすれば、そのサイトがユーザのために書かれたかものかどうかがわかる。ユーザというのはリストの項目を全部読む、というよりは、流し読みをするものだからだ。 http://tc.eserver.org/34907.html http://tc.eserver.org/34907.html オンラインコンテンツは、文脈とは無関係にユーザーの目にとまることが多い。本来想定された目的とは違う目的で読まれることもよくある。そうした目的を全部予測することはできないが、テキストのさまざまな利用を考慮することはできる。