http://tc.eserver.org/dir/Articles/Writing/Technical-Writing/Technical-Writing A listing of the most recently indexed works about Articles and Writing and Technical Writing and 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/Articles/Writing/Technical-Writing/Technical-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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/34119.html http://tc.eserver.org/34119.html Documentation is a huge cost factor in software development, and companies are looking for ways to trim costs. If you cut back on product doc and customers don't complain, there's a temptation to keep cutting. Eventually you end up with software engineers writing bits of doc because all the tech writers were laid off, but there'll be one guy who didn't get laid off who has to work like heck to wire it all up and make it continue to look like professionally written doc. http://tc.eserver.org/34112.html http://tc.eserver.org/34112.html The more skilled and experienced the readers are, the more they hate to be told in minute detail what to do. The more skilled and experienced the readers are, the more they like Checklists instead of detailed procedural steps. http://tc.eserver.org/34113.html http://tc.eserver.org/34113.html Organize your writing so that it becomes very clear what kind of cause-and-effect relationship exists between different elements of your argument. http://tc.eserver.org/34114.html http://tc.eserver.org/34114.html You can use the “Hamburger Paradigm” of writing not only for technical articles and copy but for other types of communications as well, ranging from emails to criticism. http://tc.eserver.org/34105.html http://tc.eserver.org/34105.html The parallels between the theories of technical communications and those of web design are very similar, the key aim is to keep the audience in mind at all times. The way you structure and present the information is also important, as is a sense of usability of the content itself. http://tc.eserver.org/34070.html http://tc.eserver.org/34070.html While the concepts of structured authoring are more than just slightly useful for technical writing, they can be beneficial for just about any writing task within an organization. But how do you bring XML-based structured authoring to the masses? Perhaps by taking a cue from a word processor called Yeah Write. http://tc.eserver.org/34073.html http://tc.eserver.org/34073.html New York Times gadget guy David Pogue, a former Broadway orchestra conductor and MacWorld back-page columnist, is probably the world's most widely read and watched tech product reviewer. As a fellow contributor to the Times, I can confirm that anything Pogue writes pulls down several times as many page views as my most popular work. How does he do it? http://tc.eserver.org/34059.html http://tc.eserver.org/34059.html There is no doubt that medical communications is a very young field. The clearest picture of the issues, problems, and needs of a discourse community with as complex a membership as that of medical communicators comes from the AMWA materials. Drawing boundaries between academic vs. medical professional vs. medical communicator seems pointless because of the nature of the medical communication. It also seems to be an area ripe for study by those interested in power issues in rhetoric and certainly in research in communication systems. Medical communication really is both the most and least specialized area of technical communication. http://tc.eserver.org/34032.html http://tc.eserver.org/34032.html Microsoft’s Visual SourceSafe was not created with technical communicators in mind. It was created for engineers writing software source code. But it is successfully used by technical writers in offices around the world to control documentation. http://tc.eserver.org/34034.html http://tc.eserver.org/34034.html Web writing is one of those assignments that technical writers do well due to their organized approach to technical information. But web writing differs from regular user guide and procedural writing in some important respects. The Web is a fast place. People usually don’t have the time to go through long essays. http://tc.eserver.org/34037.html http://tc.eserver.org/34037.html As a technical writer you’ve heard this piece of sage writing advice a thousand times: you should stay away from jargon and write as you speak. It’s basic. Strunk & White said so, didn’t they? It’s true. But is this rule true ALL the time, unconditionally? No, I’m afraid it is not. Life has its exceptions. And so does this “rule.” http://tc.eserver.org/34038.html http://tc.eserver.org/34038.html Technical writing unsurprisingly enough, refers to writing that is technical. Although this may seem like a fallacious definition, it’s an important one to remember. Too many technical authors make the mistake of creating documentation that is either too technical, or too ‘literary’. A good technical author should be able to adjust the balance between the two to suit the end user of the documentation. Technical writing is a lot like fresh air, pervasive and yet pretty much invisible. In the weird wired world in which we find ourselves, technical writing is everywhere. Software manuals, user guides for home appliances, instructional leaflets, emails, letters, reports, technical news reports, statistics and biographies on television sports shows all are examples of technical writing to which people are exposed to on a daily basis. If you have ever tried to program the time settings on a home video recorder and flung the manual across the room in disgust, you threw a piece of technical writing (although obviously not a very good one!). http://tc.eserver.org/34039.html http://tc.eserver.org/34039.html Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly. Bullets are ideal for things-to-do, equipment, sets, collections, cooking ingredients, and all kinds of other lists. http://tc.eserver.org/34015.html http://tc.eserver.org/34015.html Anyone who reads this blog will know that I’m a strong advocate of storytelling in all forms of communications. I believe that it applies as much to technical or marketing communication as it does to your favorite novel or movie. This article applies McKee’s 10 Commandments to Technical Documentation. http://tc.eserver.org/34020.html http://tc.eserver.org/34020.html Have you considered writing White Papers for your clients, or offering them to your own prospective customers as a lead-generating device? If you operate in a technical field, I think you should definitely consider a White Paper. You can either write one ourself or have someone else write it for you. http://tc.eserver.org/34021.html http://tc.eserver.org/34021.html A technical writer will periodically need to interview Subject Matter Experts (SME) to gather information about a technical document. More often that not, and especially within the context of software development, most SMEs are engineers and software developers. But they can also be mechanical, electrical and other types of engineers, hardware installers, network engineers, testers, site foremen, call center engineers, field technicians, sales or marketing people, local dealers, etc. One cardinal rule of interviewing an SME is to do your homework well, in advance. http://tc.eserver.org/34022.html http://tc.eserver.org/34022.html Consistency of a technical documentation is what creates that subliminal sense of trust and confidence in the end-users. Someone once quipped: “it ain’t technical documentation if it ain’t boring.” This of course is not true since I always found technical documents very interesting indeed. I’m the sort of geekish person who can marvel at a well-designed user’s manual for hours and appreciate its beauty and all the effort and thinking that went into its production. I imagine how happy people would be when they use that manual and solve their problems and that, believe it or not, makes me happy as well. That’s the main reason why I’m in this business. http://tc.eserver.org/34023.html http://tc.eserver.org/34023.html Technical writing has a number of moral and ethical standards that a professional technical writer needs to comply with. Violate them at your own peril, by risking the sudden demise of your career. Here are some of these issues. http://tc.eserver.org/34024.html http://tc.eserver.org/34024.html Although I love using the proprietary software that I’ve mentioned in the first sentence, I enjoy using open source software as well since some of them are actually better than the paid software in some respects. http://tc.eserver.org/34025.html http://tc.eserver.org/34025.html Technical writing has its mechanical aspects that need to be mastered. A good technical writer must know how to use English effectively as well as various software products to produce acceptable technical documents. But I wish technical writing were all about that. The hardest part comes before one even sits down in front of a computer to type the first word. The hardest part in documenting anything is organizing the information in a way that makes sense from the user’s point of view. Otherwise a technical document suddenly looks irrelevant. http://tc.eserver.org/34027.html http://tc.eserver.org/34027.html Using the structured features requires advanced training and you probably won’t need them anyways unless you’re doing any “single sourcing” (which is the topic of yet another article). For example if you were doing any XML-based authoring or “database publishing” then you would definitely need to learn how to use the FrameMaker’s structured interface. However, there is an easy way to imitate structured documentation while you are still in the unstructured mode. This is one case in which you can have your cake (unstructured FM) and take a bite out of it too (by enjoying one selected feature of structured documentation). http://tc.eserver.org/34028.html http://tc.eserver.org/34028.html Here are seven time-tested design recommendations culled from my 20 years of experience as a professional writer, page layout and information designer. http://tc.eserver.org/33952.html http://tc.eserver.org/33952.html When it comes to modern theater, stage directions—the descriptive text that appears within brackets in a script—are an important piece of the puzzle. They speak for the playwright when he is not there. They provide details about how the playwright has imagined the environment and atmosphere. They describe critical physical aspects of the characters and settings. Stage directions can also be critical in dictating the intended tempo and rhythm of the piece. Whether they establish a production’s overall tone or elucidate particular actions of characters, stage directions help tell the complete story that is in the playwright’s mind. Stage directions accomplish all of this, using a simple convention that structurally separates them from the actual story.