http://tc.eserver.org/dir/Technical-Writing A listing of the most recently indexed works about Technical 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/Technical-Writing 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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/34863.html http://tc.eserver.org/34863.html Capturing the essence of a topic is the heart and soul of good writing and editing. If you cannot tell what the main idea is, you cannot write it either. And if you cannot write it, how would you expect your readers to get it? So it all starts with you. Thankfully, it is not mysterious process. Here are two techniques that you can use to weed out the irrelevant details from your core idea. http://tc.eserver.org/34867.html http://tc.eserver.org/34867.html Pay attention to the legal requirements and translatability issues, not only in your own documents, but in the documents of other groups like marketing and engineering. It's an area where we add value. http://tc.eserver.org/34802.html http://tc.eserver.org/34802.html For some years, people, myself included, have noted the lack of interest, even disdain, that many tech writers have for business issues. This reduces these writers' ability to affect company decisions, including decisions that may affect them. Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions. http://tc.eserver.org/34804.html http://tc.eserver.org/34804.html Sure. We’ve been reducing word count in procedures for some time. It’s time to do more, however. As noted in an earlier post, we have to think mobile. Think small screens and small devices. Screen real estate will be at a premium. http://tc.eserver.org/34775.html http://tc.eserver.org/34775.html One of the reasons that technical communicators ought to know the business processes of their users (or at least the reasons they’re using the product) is to generate effective examples in the documentation. http://tc.eserver.org/34777.html http://tc.eserver.org/34777.html In order to understand the way marketing people see the world, it’s worth reading Blogs on marketing (by people such as Seth Godin), the Cluetrain Manifesto, and reading a few books on marketing. http://tc.eserver.org/34710.html http://tc.eserver.org/34710.html The authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output. http://tc.eserver.org/34712.html http://tc.eserver.org/34712.html Help needs to be a mile wide—it must cover everything—and 30 seconds deep—tackling only small amounts of detail at any given point. http://tc.eserver.org/34713.html http://tc.eserver.org/34713.html Technical writing is a cost activity, not a revenue or a profit activity. http://tc.eserver.org/34716.html http://tc.eserver.org/34716.html Always keep the small screen in mind when you’re preparing your docs. There are some W3C “mobileOK” guidelines to consider to ensure that your content meets requirements. Here are some highlights. http://tc.eserver.org/34717.html http://tc.eserver.org/34717.html More and more, I think it’s time to discard main approaches to tech writing and come up with new methodologies. The world and technology is changing so much that I think it’s time to start fresh. Just as sometimes when you’re working on a sentence and you tweak it and change it, but it’s still not quite right, and you finally just drop it and come up with something different. Perhaps it’s time to drop existing methodologies and develop something new instead of trying to tweak what’s there to fit what’s happening now. Perhaps the old methods no longer work. http://tc.eserver.org/34706.html http://tc.eserver.org/34706.html Documentation for consumer products gets a bad rap. Often, it's deserved. But you can't paint all documentation with the same brush. This post looks at the good and the bad in consumer documentation, and at the elements which can make that documentation good. 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/34698.html http://tc.eserver.org/34698.html It’s often useful to look at the economic and technological pressures in other industries, to see if the trends emerging there are relevant to the technical communications/publications sector. In recent Blogs, we’ve covered the issues emerging in education, but the telecommunications industry might also provide some useful insights. http://tc.eserver.org/34682.html http://tc.eserver.org/34682.html Writing user manuals isn't so difficult if you start with a clear understanding of the structure of such documents. This post will provide you with some guidelines for producing a great manual, and links to templates to help you get started. http://tc.eserver.org/34683.html http://tc.eserver.org/34683.html Technical writing is sort of a jack-of-all-trades profession. It requires diverse skills, so a lot of people stumble into technical writing by chance. I've personally met technical writers who used to be lawyers, educators, and published fiction writers, and I've heard stories of many other professionals drifting into the field. Their past careers required writing, teaching, or technical abilities, and these skills helped them segue into a technical writing job. http://tc.eserver.org/34677.html http://tc.eserver.org/34677.html Really, I think documenting the software the way it works with bugs is making more work for myself, so that’s probably the main reason I avoid it. I’ve got enough to do without changing the doucmentation whenever a bug is fixed. Release notes are easier—a much smaller deliverable whose focus is what’s changed and what’s still not quite right. http://tc.eserver.org/34650.html http://tc.eserver.org/34650.html Technical writers are Jills and Jacks of all trades. But what really makes a tech writer tick? In this guest post, Sarah Maddox explores that question and comes up with some interesting answers. http://tc.eserver.org/34640.html http://tc.eserver.org/34640.html There is most definitely a technical communicator identity crisis underway. Three posts from well respected industry professionals in the span of one month, all dealing with a fundamental shift in an core product development profession. What’s going on here? To put it plainly: documentation now has competition. http://tc.eserver.org/34646.html http://tc.eserver.org/34646.html The best technical writers do user research to understand the audience for their documentation, create user profiles or personas, perform task analyses, and do usability testing to ensure that their documentation meets users’ needs. All of these are activities in which a user researcher engages. Thus, as a technical writer, you can start amassing experience in user research and building a portfolio of user research documentation. http://tc.eserver.org/34649.html http://tc.eserver.org/34649.html I’m going to start with a short introduction to Twitter, mentioning particularly the aspects that I found useful when tweeting release notes. If you’re already a twitterologist, you may want to skip that bit. Then I’ll describe how we’ve used Twitter as a method of communicating the highlights of our release notes. http://tc.eserver.org/34586.html http://tc.eserver.org/34586.html Finding information in documentation is easy. Or is it? This blog post argues that there's no universal solution, and that each document and each delivery method offers challenges and requires a slightly different solution. http://tc.eserver.org/34581.html http://tc.eserver.org/34581.html Words is a free, quarterly bulletin for technical writers and communicators—indeed, for anyone with a passion for words and for what you can do with them. Each issue of Words will include articles on language, authoring tools and authoring methodologies. Occasionally, other topics will be covered, such as document design, usability and audience profiling. There will also be reviews of books and software from time to time. http://tc.eserver.org/34574.html http://tc.eserver.org/34574.html Some advice on writing articles about technology (and other topics) for a mass audience. http://tc.eserver.org/34544.html http://tc.eserver.org/34544.html When you think of the crowd, you probably think about a specific mass of people who use the software and hardware that we document every day. The interesting thing about the crowd is that it doesn’t necessarily mean people outside of the enterprise in which you’re working. There are people in your enterprise who can do a lot to help you with the documentation, too. Developer, product managers, QA analysts. They all have knowledge that you can and should tap. http://tc.eserver.org/34545.html http://tc.eserver.org/34545.html Do we need to have an external help system? Why not embed help right into the application? Why not take this a step or two further? Instead of having a separate help system, integrate more useful, more robust, and context-sensitive help into the user interface. http://tc.eserver.org/34548.html http://tc.eserver.org/34548.html A musing on the need to balance documenation that looks good with documentation that has substance. http://tc.eserver.org/34552.html http://tc.eserver.org/34552.html Users want to know how to do things, and not be told what a piece of software or hardware can do. And good those users can adapt, can work around any ignorance they have, and when needed fill in any gaps in their knowledge. http://tc.eserver.org/34515.html http://tc.eserver.org/34515.html Technical writers are an important and underutilized asset to most businesses; however, I also believe that technical writers have to fundamentally alter the way they approach the problem of educating users and helping them find the answers they need before they will be properly valued by the businesses that employ them. http://tc.eserver.org/34516.html http://tc.eserver.org/34516.html Products and tools must evolve to ensure that user experience does not suffer as technical writers evolve their delivery to suit this modern age. If a user has a question, there should be only one place to search, and those results should contain relevant hits from all possible content sources. http://tc.eserver.org/34517.html http://tc.eserver.org/34517.html Technical writing is a profession in transition. The way companies think of, use, and manage the people who help users make sense of and use products is absolutely changing. A lot of companies have started to use the term “information developer” to describe their technical writing positions. I don’t really care what label the profession chooses for itself, but I do know this: if technical writers don’t transition more than their job title then they will be missing out on a huge opportunity to move from the “gotta do it” category into the “can’t live without it” one. http://tc.eserver.org/34518.html http://tc.eserver.org/34518.html I’ve been browsing a lot of online documentation lately and in a past life I spent an enormous amount of time worrying about how my users were interacting with documentation. It never ceases to amaze me how bad most product documentation is, especially when the documentation is published in a half-measured attempt on the web. Do companies not realize the negative effect poor documentation, both content and presentation, have on their users? http://tc.eserver.org/34520.html http://tc.eserver.org/34520.html Most questions have been asked before. This isn’t a profound statement; most of us would consider it obvious. Just ask anyone on your Product Support team. Chances are the majority of calls they receive are fielded with canned answers. Why? Because we all seem to ask the same questions. By providing answers to those questions, you can help the majority of your users get back on track quickly. http://tc.eserver.org/34500.html http://tc.eserver.org/34500.html Want to learn more about tech writing and about the work tech writers do? Below are some links of general interest that will point you in useful directions. I believe that anyone new to the field should browse them all. http://tc.eserver.org/34489.html http://tc.eserver.org/34489.html It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways. http://tc.eserver.org/34490.html http://tc.eserver.org/34490.html In the world of development, the need to track bug reports and enhancement requests are a given. But they're not generally required for documentation, in the way they are for code Quite the reverse. For documentation, bug reports and enhancement requests provide little benefit, and generally impede progress. This post compares documentation and code, showing why bug reports and enhancement requests are so vital to the code base, and at the same time why those reasons simply do not apply to documentation. http://tc.eserver.org/34476.html http://tc.eserver.org/34476.html Writing is a complex, cyclical task. The writing task requires more than formulating text to express ideas, it involves data gathering, managing constraints, formulating intentions, planning, and revising goals. Much of the complexity is due to the management of simultaneous activities and constraints. Management of these processes can lead to 'cognitive overload', which in turn can negatively affect the quality of the text produced. With technical writing, these same issues of task complexity are applicable. http://tc.eserver.org/34434.html http://tc.eserver.org/34434.html A technical writer is a professional writer who designs, writes, creates, maintains and updates technical documentation including online help, user guidance, white papers, design specifications, system manuals and other documents. A technical writer should possess good research techniques, good sound of language and excellent writing skills. Apart from this one needs to have the following five skills. http://tc.eserver.org/34446.html http://tc.eserver.org/34446.html A colleague has made me realize that user assistance writers are codependents of bad UI design. Because we explain how the UI really works, we somehow leave our developers and companies feeling like they're "covered" when the users have a bad experience. http://tc.eserver.org/34416.html http://tc.eserver.org/34416.html Knowing your document’s intended reading audience before you begin writing will always help you write more effective documentation. There are three simple questions you should always ask before you start writing. http://tc.eserver.org/34411.html http://tc.eserver.org/34411.html None of the technologies mentioned so far support the production of content for purposes of producing technical documentation. Such a system is a specific type of content management that has specialized functions for technical communicators doing multi-channel publishing, yet it hasn't spun off its own specific acronym. http://tc.eserver.org/34398.html http://tc.eserver.org/34398.html I have been dwelling for some time with ideas for rethinking the professional writing major in response to phenomena that aren’t going away, such as the inadequacy of the university for life-long learning and the unsustainable way that public education is funded. http://tc.eserver.org/34403.html http://tc.eserver.org/34403.html If you’re a generalist, as most tech writers are, you write about many things in a variety of media with a number of objectives. Each new job involves determining who your audience is, what their needs are, and how your product or service can satisfy those needs. Then you need to recognize, understand, and adjust your writing so one time it appeals to the camper and the next time to the business owner. http://tc.eserver.org/34387.html http://tc.eserver.org/34387.html The most effective and powerful resumes provide analytical, precise detail about your background and achievements. In fact, resume writing has a strong correlation to technical writing in that both styles demand extreme precision. In fact, most readers of your resume will assume that what you show on paper correlates strongly to what you can do for your next employer. http://tc.eserver.org/34385.html http://tc.eserver.org/34385.html Citing the rise of graphic novels, comics, and in particular, Google’s new web browser Chrome, which has a comic-book-style manual, Opsteegh argues that technical communicators can learn a thing or two about conveying information from graphic novelists. http://tc.eserver.org/34378.html http://tc.eserver.org/34378.html Users would save time by reading the manual, but instead they try to figure the application out themselves and then get lost/frustrated as they end up spending even more time getting up to speed with the application. http://tc.eserver.org/34382.html http://tc.eserver.org/34382.html Users often want documentation in a format that will give them the basics and get them on their way as fast as possible. Quick reference guides provide a short version of a manual, condensed from dozens or hundreds of pages down to just one double-sided sheet of paper. Despite the brevity of quick reference material, the thought process involved in creating, organizing, and laying out the content is time consuming. The format requires you to assess the content and decide the most important information the user needs to know. You must describe with extreme concision and clarity processes that usually require dozens of pages to explain. This article provides an overview of the strategies, tips, challenges, and benefits we have learned in using quick reference guides for our documentation projects. http://tc.eserver.org/34369.html http://tc.eserver.org/34369.html This presentation describes the standard structure of a lab report and provides a methodology for successfully producing such a report. It includes a description of the generic structure of a report and variations on this theme. http://tc.eserver.org/34370.html http://tc.eserver.org/34370.html Technical Writing explained using photographs of actual technical writers. http://tc.eserver.org/34371.html http://tc.eserver.org/34371.html The mindset in which most technical communicators write help is sometimes fundamentally flawed. Consider the following two stories and the different approaches and mindsets each writer takes toward the project. http://tc.eserver.org/34340.html http://tc.eserver.org/34340.html I’m enough of a perfectionist that I mentally wince every time I find myself thinking, “It’s good enough.” It sounds like a cop-out. It sounds like avoidance of responsibility and ownership. It sounds like I’m indifferent. http://tc.eserver.org/34322.html http://tc.eserver.org/34322.html Technical writing is the presentation of information that helps the reader solve a particular problem. Technical communicators write, design, and/or edit proposals, manuals, web pages, lab reports, newsletters, and many other kinds of professional documents. http://tc.eserver.org/34328.html http://tc.eserver.org/34328.html If we really do believe in the importance of the audience, the reader, the user, then how have we changed our practice to reflect the changing characteristics, competencies and even literacies of our readers? Have our readers changed over the past few years? The evidence points to the answer being a resounding yes! http://tc.eserver.org/34271.html http://tc.eserver.org/34271.html Dark text refers to the many layers of hidden meaning in any text segment. It ranges from the implied meaning that the author intended, or that the reader infers, to much deeper, more hidden meanings. As technical writers, we must be aware of dark text, and where possible, try to minimize it. 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/34265.html http://tc.eserver.org/34265.html Rather than spend hours coming up with a complex numbering scheme, this might be an excuse to implement something far more straightforward discovered by an extensive readability study at IBM, of which I was a part. My work involved sitting behind a one-way mirror with a stopwatch, watching people take tests that involved, among other things, "how fast can you find Figure 3-4?" We had cameras mounted over the participant's shoulders and could watch them thumb through the documents, and we also monitored eye movements. Then we followed up with a short interview where we got feedback. http://tc.eserver.org/34266.html http://tc.eserver.org/34266.html Technical authors are faced with limited time and resources, so they often are faced with the dilemma as to what to include and what to leave out of their user documentation. You may ask, if 80% read only 20% of the content, is there any value in documenting the rest? http://tc.eserver.org/34252.html http://tc.eserver.org/34252.html In this article, my colleague and I provide strategies, tips, and approaches we’ve learned in creating quick reference guides for software documentation projects. http://tc.eserver.org/34157.html http://tc.eserver.org/34157.html This article offers tips on breaking into the field of freelance writing—some from Alice Osborn herself, some from two of the books she recommends: "Secrets of a Freelance Writer" by Robert W. Bly; and "The Renegade Writer" by Linda Formichelli and Diana Burrell. http://tc.eserver.org/34159.html http://tc.eserver.org/34159.html This set of guidelines was developed to help you understand the expectations for technical communication in CE 314K (Properties and Behavior of Engineering Materials). Successful technical communication requires practice. Therefore, you should allot sufficient time to write several drafts of each assignment before submitting the final version. http://tc.eserver.org/34160.html http://tc.eserver.org/34160.html How to get lab discoveries and results into a written document.