#13515
Documentation Testing Checklist 
Check out this new Documentation Testing Checklist, which offers categories and suggestions to use when testing documentation.
O'Sullivan, Cara. TECHWR-L (2002). Resources>Usability>Tools
#19766
E-Mail, Acronyms, and Alphabet Soup
Emoticons have become pretty complex, now including ones like :-# [lips are sealed], :-& [tongue tied], or :-'' [pursing lips].
Ray, Deborah S. TECHWR-L (1998). Humor>Writing>Correspondence>Email
#19180
Too many editors focus on the details and don't pay enough attention to the bigger picture. Editors can--and should--add even more value through substantive, technical, and usability editing. Copyediting is important, but the details are only part of what an editor can and should be reviewing. After all, a document can be correctly spelled and punctuated, grammatically correct, use only approved terminology, and follow the style guide perfectly--and still not serve the audience's needs. This article covers some reasons why editors focus on details and not the bigger picture; describes how much attention technical communicators should pay to formal rules of grammar, punctuation, and usage; and describes how we can distinguish between essential and nonessential rules of grammar, punctuation, and usage.
Weber, Jean Hollis. TECHWR-L (2002). Articles>Editing>Grammar
#13053
Essential Resources for FrameMaker Users
FrameMaker may be the current standard for technical publication, but that doesn't mean it's a perfect program. Many writers who've used FrameMaker find that it's complex and quirky, with a lot functionality hidden in its now somewhat dated interface. So where do you go when you need help? This article will give you some suggestions.
Soltys, Keith. TECHWR-L (2001). Articles>Document Design>Software>Adobe FrameMaker
#14146
Establishing and Building Mutual Respect with Technical Team Members
As a technical writer, are you finding yourself wishing for just a bit of respect from the engineers, SMEs (Subject Matter Experts), or other technical people you work with? Are you finding that these folks seem to stonewall you on every question you have or every goal you're trying to achieve? Are they obstreperous? Difficult? Or just plain unhelpful? When I hear technical writers complaining about--er, describing--such troubles when working in a team environment, my first reaction is to want to sit and observe how they actually interact with those seemingly impossible team members. In my experience, I've found that the problem isn't always with a surly SME or with an engineer who lacks communication skills. Certainly, there are cases where other team members just don't value any contribution other than their own; however, most often, I have found the problem is with the technical writer's approach to the team environment--and have found that the problem began from the very start of that writer's involvement with the team.
Ray, Eric J. TECHWR-L (2002). Careers>Collaboration>Workplace>SMEs
#14141
An example worksheet for generating TC job estimates.
#14139
This document accompanies the TECHWR-L article 'Developing a Style Guide,' and includes a sample outline of a style guide. Some of the sections include some detailed sample text; others do not. Please note that the examples shown here are not necessarily the 'correct' choices, or the 'preferred' choices, or the 'best' choices; they are simply examples of things to include. Your project may require additional items, especially if your writing will be used on a Web site.
Weber, Jean Hollis. TECHWR-L (1998). Reference>Style Guides
#12934
Extending Your Tech Writing Skills: Pitching a Newspaper Column Idea
Before pitching a column idea to your local newspaper editor, take time to examine whether becoming a columnist is right for you. In taking on a newspaper column, you not only take on a long-term commitment, but you also establish a responsibility to people in your own community. So, to begin, you might read Extending Your Tech Writing Skills: Becoming a Columnist, which identifies considerations for becoming a columnist. If you decide that becoming a columnist does suit your interests and goals, then the following tips and ideas can help you land a column with your local newspaper. As you'll see, examining and refining the topic, overcoming the competition, using a creative approach, and following up appropriately can help.
Ray, Deborah S. TECHWR-L (2001). Articles>Writing>Collaboration
#13487
Feng Shui for the Tech Writer's Workspace
It sounds like something from a late-night infomercial: Enhance your productivity by cranking out online help files in half the time! Increase your prosperity by being promoted to head of the documentation department! Improve your interpersonal relations so that Subject Matter Experts (SMEs) are just waiting to review your documents. Ensure a long and healthy life, despite the stress of vaporware product launches! If an advertisement lurking in your emailbox claimed to have an ancient secret to give you all the above, you'd likely press Delete faster than you can say 'looming deadlines.' But what if millions of people--some as well-known and successful as Donald Trump--and major corporations, such as Virgin Airlines, The Wall Street Journal, and Citibank, attested to this 'magic' secret's power? In that case, you just might sit back in your office chair and listen.
Chroust Ehmann, Lain. TECHWR-L (2002). Careers>Workplace>Ergonomics>SMEs
#14256
For decades, journalists have used a proven approach called the 'Five W's' to answer the questions that the readers of newspaper articles most commonly want writers to answer. The questions are sufficiently useful that they can easily be applied outside newspaper writing, and I've already written about this in the context of audience analysis (Hart 1996). In this article, I'll show you how you can use these questions to develop more useful online help. Each of the five W's is a simple question that starts with the letter W: Why, Who, What, Where, and When. Some authorities add a sixth question, 'How,' to this list, but 'how to' information generally fits under what, where, or when, depending on the nature of the information. Users of online help can benefit greatly from the proven journalistic approach if we can answer these same five questions for each help topic that we create. In the remainder of this article, I'll provide an example of a failure to ask these questions, show how asking these five questions could have prevented this failure, and provide examples of typical questions we should be asking. Please note that, although I've presented these five questions in an order that seems logical to me, in practice the approach becomes iterative: It doesn't much matter where you begin, since answering one question often reveals important aspects of the other questions that you'd not yet considered.
Hart, Geoffrey J.S. TECHWR-L (2002). Articles>Documentation>Help
#12933
While writing attention-grabbing, informative queries--a much-covered topic in the freelance writing arena--is important in landing assignments, don't overlook one important aspect that can help you continue landing assignments time after time: Establishing and maintaining good relationships with the editors you work with. This article offers advice, how-to and why-to information, and techniques to apply throughout the publishing process that can help you build good relationships with magazine editors. Although the following sections provide specific details and steps, the message is simple: A little understanding, consideration, and effort go a long way.
Ray, Deborah S. TECHWR-L (2001). Articles>Writing>Collaboration
#13363
Gender-Neutral Technical Writing
Gender-neutral writing uses language that does not stereotype either sex nor appear to be referring to only one sex when that is not the writer's intention. In this article, you'll see why gender-neutral writing is important for technical writers to use, what gender-neutral writing is not, and how you can use gender-neutral writing in the documents you develop.
Weber, Jean Hollis. TECHWR-L (2002). Articles>Writing>Style Guides>Gender
#14138
Getting Started in Technical Writing
This summary provides a collection of tips and advice for getting started in the technical writing profession. The following categories are included in this summary: Finding and Getting That First Job; Types of Technical Writing; Types of Technical Writers; Degrees and Technical Writing; Transferring to Technical Writing from Other Professions: From Journalism; From Teaching; From Academia; From Marketing; From Law; Essential Skills; On Being a Technical Writer.
#12964
Good, Fast, Cheap: Translation Memory Systems Offer the Potential for All Three
For technical communicators exploring translation services, a relatively new technology can help provide consistency among translated documents, make the translation process more efficient, and make translation projects cost effective. Translation memory systems assist human translators by following along as a document is translated, creating a database of translated material and terminology, and allowing translators to access previously translated material easily. Using this technology, translators can translate, save, and reuse material, making the resulting translations highly consistent and the overall process more efficient and cost effective than working without this technology. In this exploratory article, we explain the evolution toward translation memory systems, discuss why and when they're particularly useful for helping translate technical documentation, and offer guidelines for determining whether translation memory systems are appropriate for your translation needs.
Ray, Deborah S. and Eric J. Ray. TECHWR-L (1999). Articles>Language>Localization
#14134
Guidelines for Technical Edits
The purpose of the technical edit is to ensure that all materials produced by the Documentation department are as complete and technically accurate as possible. Each document will also pass through a peer edit by a member of the Documentation department after the technical edit is complete, so as a technical editor you do not need to be concerned with issues of style and grammar. Your main focus should be on the technical accuracy of the document. The first step, of course, is simply to check the document for any errors. We need to make sure w have correctly described each feature of the software, as well as the overall design and purpose of the forms and systems we are discussing. Beyond checking for errors, however, we want the documentation we produce to be as helpful to the user as possible. For the purposes of the technical edit, this means not only checking for inaccuracies, but asking whether the document has all the information that is necessary to use the software successfully.
#12963
The idea behind Open Source is simple: everyone should have the freedom to copy, distribute, and change source code. The implications, however, overturn the conventional high-tech business model. When software is no longer intellectual property, everything changes. Development is quicker because more people are involved. Bugs are caught more quickly. Instead of being passive consumers, customers can become partners in development. Instead of selling software, companies sell hardware, services, or added value. Internally, companies become more interactive and more loosely structured. If Open Source continues to gather speed, high-tech workers will discover that it is not just a development model, but also a new model for corporate life. For writers, the approach of Open Source could be especially important. How documentation is viewed and used, how writers interact with developers, and what tools are used--all of these and more could be affected by the Open Source movement.
Byfield, Bruce. TECHWR-L (2000). Articles>Software>Open Source
#22455
Review: Hot Text: Web Writing That Works
This book will help you improve any type of written communication, and it's a fun read to boot. The authors know what they're talking about and have the experience to back up their words. Both have spent many years writing for Web audiences. In addition to Web writing, their combined relevant experience includes journalism, technical communication, art, TV and radio, and teaching.
Frick, Geri. TECHWR-L (2004). Articles>Reviews>Web Design>Writing
#10794
How come...everyone still says there is 'an error in the docs!'
Gooch, Chris. TECHWR-L (1999). Humor>Writing
#10799
A dog-ate-my-homework computer failure from the Ray computer logs.
Ray, Deborah S. TECHWR-L (1998). Humor>Computing
#12945
The Inappropriate Posting Scenario
You are in a large lecture hall full of people in your profession. Included in the audience are students, educators, professionals. You cannot make out their faces, but they could reasonably include your employers or potential employers, your coworkers, and the ever-present violently obsessive technical writing groupies. Most of the audience members sit quietly as one member at a time gets up, walks to the podium, and shares information or advice or asks questions. Some of it is rich and detailed, some cursory but helpful, some trivial but relevant in a roundabout way. Somewhere in this stream of information, someone expresses an opinion or gives a piece of advice that you feel obligated to respond to.
#26126
Increasing Visibility: Building Demand for Technical Communication Services
Good technical communication is critical to the success of products and ultimately to the success of companies. But even the most perfect manuals may go unread, and the most elegant help systems may go unnoticed unless you take the time to promote the quality and necessity of your work. You need to showcase your talents and to encourage people throughout your company--and the community--to value and understand the work that you do. This will ideally lead to more respect, better pay, and more interesting work.
Huettner, Brenda P. TECHWR-L (2005). Articles>TC>Marketing
#19941
Increasing Visibility: Building Demand for Technical Communication Services
Good technical communication is critical to the success of products and ultimately to the success of companies. But even the most perfect manuals may go unread, and the most elegant help systems may go unnoticed unless you take the time to promote the quality and necessity of your work. You need to showcase your talents and to encourage people throughout your company--and the community--to value and understand the work that you do. This will ideally lead to more respect, better pay, and more interesting work.
Huettner, Brenda P. TECHWR-L (2003). Careers>Freelance>TC
#19515
Increasing Visibility: Building Demand for Technical Communication Services
Good technical communication is critical to the success of products and ultimately to the success of companies. But even the most perfect manuals may go unread, and the most elegant help systems may go unnoticed unless you take the time to promote the quality and necessity of your work. You need to showcase your talents and to encourage people throughout your company--and the community--to value and understand the work that you do. This will ideally lead to more respect, better pay, and more interesting work.
Huettner, Brenda P. TECHWR-L (2003). Articles>TC>Workplace
#12954
Knowing When to Upgrade Software
Software upgrades generally do two things: Offer you new or improved features, and fix bugs present in existing versions. Whether you upgrade will depend on your need for the new or improved features, depend on whether you experience problems because of software bugs, and, of course, depend on your budget.
Ray, Deborah S. and Eric J. Ray. TECHWR-L (2001). Articles>Software
#22456
Review: Life in the New Work Order, or What Was I Doing Reading Death March?
So what is there in this book for the technical writer? There is some obvious advice, such as don't enforce a process that gets in the way of reaching goals; and don't try out radically new tools on this project. There is also good advice that most of us would take years to discover on our own, about the high-level politics that might help the project and some strategies to try during negotiation. If you are managing a group, it also gives some ideas on the different social roles that every team seems to need.
Lizak, Samantha. TECHWR-L (2004). Articles>Reviews>Project Management
