http://tc.eserver.org/publisher/Boston_Broadside A listing of works published by Boston Broadside in the field of technical communication. 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/Boston_Broadside http://tc.eserver.org/30347.html http://tc.eserver.org/30347.html This article discusses some important issues in implementing a software documentation review process. If you are part of a small development organization and have few reviewer resources available, you may have to improvise techniques for providing the services and procedures suggested here. http://tc.eserver.org/30351.html http://tc.eserver.org/30351.html The emergence of the web has accelerated the convergence of marketing communications, training, and technical communication. Marketing communicators are increasingly producing users' guides, trainers are producing wizards and marketing materials. Technical communicators are producing tutorials and pre-sales literature. http://tc.eserver.org/30348.html http://tc.eserver.org/30348.html Use active voice, because it is easier to understand. If the material is being translated into a language which frequently uses passive voice, such as German, the translator will make the accommodation for that language. http://tc.eserver.org/30358.html http://tc.eserver.org/30358.html When is a noun not a noun? When it's been verbed. A lot of verbing is going on, as you've probably noticed. In fact, it's happening so frequently that I think we'd better come up with a name for the part of speech produced by verbing a noun. http://tc.eserver.org/30353.html http://tc.eserver.org/30353.html How to tie down the details of a project and protect yourself from unexpected changes that can drag a 'peach project' into the 'pits of despair and financial ruin.' http://tc.eserver.org/30357.html http://tc.eserver.org/30357.html The freedom to be a consultant or independent contractor (C&IC), to work on your own, to work at home, to 'tele-commute' has become one of the principal aspects that entices otherwise happy, healthy, sane people to leave their jobs and hang out their shingles. But like nearly every other aspect of being independently employed, working out of the home presents advantages and disadvantages in such areas as lifestyle, professionalism, and tax considerations. http://tc.eserver.org/30355.html http://tc.eserver.org/30355.html Assigning responsibility without sharing authority is like making someone a peanut butter and jelly sandwich, but leaving out the bread. They know what they're supposed to chew, but have absolutely no way to handle, no way to manage the project. http://tc.eserver.org/30346.html http://tc.eserver.org/30346.html In addition to creating product specifications in support of locale-specific conventions, savvy localization managers will ensure that developers have coding practices to enable localization and adaptation. Double-byte enabling, for example, must be part of the code base. http://tc.eserver.org/30350.html http://tc.eserver.org/30350.html You can add to customer satisfaction by letting customers know you are committed to the market in their country, when you provide information in their own language. You can increase sales because buyers can find your company Web site; learn about your products in their own language, get connected to the nearest outlet, or place orders online. http://tc.eserver.org/30356.html http://tc.eserver.org/30356.html The funny thing is, this rule should be running out of steam, because certain standards of written English have changed in ways that make the rule at least partly obsolete. Learning it is kind of like learning to change a cloth ribbon on an old manual typewriter. http://tc.eserver.org/30352.html http://tc.eserver.org/30352.html Structure is a fundamental construct of mathematics. The field of discrete mathematics, in fact, is the foundation of data structures, upon which computer science is built. http://tc.eserver.org/30345.html http://tc.eserver.org/30345.html A well-thought-out design and well-written content reduces the time required for good international products and saves money. As a bonus, most internationalization issues apply across all languages and usually help improve the quality of the American-language product as well. http://tc.eserver.org/30349.html http://tc.eserver.org/30349.html Leverage, CAT, translation memory, and aligning are quite interrelated and build on each other in the process. http://tc.eserver.org/30354.html http://tc.eserver.org/30354.html The most coveted writing assignment in the computer industry is the overview of an integrated software package. It calls for careful pacing, creative metaphor, and lavish graphics, all integrated with the highest skill. Here stands the pinnacle of a career, to be 'writing at the user interface.' http://tc.eserver.org/30343.html http://tc.eserver.org/30343.html The liability of a translated manual is several times greater than the English version. This increased liability can be tied directly to the accuracy of the translation. http://tc.eserver.org/30324.html http://tc.eserver.org/30324.html What do you do about medical insurance coverage if you are laid off? http://tc.eserver.org/30333.html http://tc.eserver.org/30333.html Next to writing an enthusiastic thank you note for socks received as a birthday gift, the most difficult task for many writers is creating a help wanted ad that succinctly defines the requirements of the position while encouraging only perfect candidates to apply. http://tc.eserver.org/30344.html http://tc.eserver.org/30344.html The first impulse of many documenters is to turn our work over to editors and graphic designers, or to form committees and develop style guidelines. All of these measures are useful, but none can assure us of quality when there are basic problems with the way we go about producing documentation. http://tc.eserver.org/30319.html http://tc.eserver.org/30319.html When you get fed up and do decide to blaze your own trail, don't forget to take some friends along with you. You never know when you're going to run into a wild past participle that you need help taming. http://tc.eserver.org/30326.html http://tc.eserver.org/30326.html If listening isn't in the mix when developing documentation, then the project may not cook. http://tc.eserver.org/30334.html http://tc.eserver.org/30334.html This two-part article looks at the comparative costs of employees versus independent contractors, helps you to classify workers as either independent contractors or employees, and (in the second part) will examine the consequences of misclassification as it affects clients, independent contractors, and third party payers (such as a consulting firm or a contract agency). http://tc.eserver.org/30336.html http://tc.eserver.org/30336.html This article examines some of the consequences of misclassifying workers as independent contractors when they should be treated as employees. http://tc.eserver.org/30338.html http://tc.eserver.org/30338.html I think it can be dangerous for a technical writer to be a grammar expert. http://tc.eserver.org/30325.html http://tc.eserver.org/30325.html NetWorks is an association of people involved in public relations, technical/computer documentation, marketing, fund raising, planning and development, training, journalism, editing, video production and publishing. We have a common interest in sharing ideas, information and resources. http://tc.eserver.org/30335.html http://tc.eserver.org/30335.html Whether one teaches business communication or technical writing (or some amalgam of the two), the first statements an instructor makes in class should be to apprise students that the course upon which they are embarking is but a specialty within a larger field of writing, that their courses in English composition, philosophy and survey of literature (and the papers written for those courses) will all apply to the specialized communication field they now must address. http://tc.eserver.org/30323.html http://tc.eserver.org/30323.html As a technical writer with over seven years of experience and a Master's degree, I am disappointed with the lack of part-time jobs and lack of responsiveness by employers to create part-time technical writing positions. http://tc.eserver.org/30318.html http://tc.eserver.org/30318.html No matter how simple a task may first appear, you're better off to thoroughly read through the documentation, especially if the equipment you're using is borrowed. I've also learned that perhaps department stores really don't charge a fortune in comparison to my home project. http://tc.eserver.org/30330.html http://tc.eserver.org/30330.html The demand for recycled paper is on the rise and more and more paper manufacturers are producing recycled paper in the same categories and range of choices as virgin stock. However, because of the variations and inconsistencies in the raw materials used, paper that contains recycled fiber tends to he at the middle to lower quality levels of each paper grade. http://tc.eserver.org/30339.html http://tc.eserver.org/30339.html The success of a technical document depends heavily on the index. The task of indexing a technical document often cannot begin until insufficient time remains to do a good job. However, for many users of the document, a good index is mandatory to its usability. http://tc.eserver.org/30322.html http://tc.eserver.org/30322.html Today's business climate is kinder to those who understand and act on the fact that there are numerous ways to communicate positive attributes. http://tc.eserver.org/30331.html http://tc.eserver.org/30331.html Technical writers are taking on more responsibilities. More and more, writers are being asked to participate in the design and review of a new product, or to help organize the efforts of a product team. Before you even begin evaluating software, resolve the following points in your own mind: Performing a comprehensive evaluation of a piece of software takes time, and chances are that no one product has all the capabilities you would like it to have, so be prepared to make concessions. http://tc.eserver.org/30321.html http://tc.eserver.org/30321.html The résumé is the key to landing a job initially, and then to advancing in the profession. So, let's consider the elements that go towards composing the ideal résumé. http://tc.eserver.org/30342.html http://tc.eserver.org/30342.html As more companies sell in the global market and recognize the importance of customer service and satisfaction, they are beginning to realize the importance of translating software and documentation into foreign languages. Once your own company realizes that it needs to translate its documentation, to whom will it turn for project management? You, of course. The technical writer is in an ideal position to control the translation of documentation and the textual element of software. http://tc.eserver.org/30337.html http://tc.eserver.org/30337.html Type is to a publication as a speaker is to an audience -- they both have to work coherently to capture and keep your attention. Type defines a publication's personality; since it's a common element on every page, it should work to achieve a visual unity throughout. Crisp, consistent, readable typography will help propel the reader through your pages. http://tc.eserver.org/30341.html http://tc.eserver.org/30341.html If you have been paid as independent contractor for work you have performed, you might assume that you are ineligible for unemployment compensation when a client or a temporary agency can no longer keep you busy. The client has no more work, so you think you're on your own to look for work, without the benefit of unemployment compensation. But what if a client or temporary agency should have paid you as an employee, instead of treating you as an independent contractor? In many cases, you would be entitled to collect unemployment compensation, even if you had signed a contract stipulating that you would not be eligible for benefits. http://tc.eserver.org/30328.html http://tc.eserver.org/30328.html Usability testing actually measures human factors as they apply to performed tasks based on the interaction between documentation and a product user. As technical communicators, we are becoming increasingly aware of the importance human factors have on our profession. http://tc.eserver.org/30327.html http://tc.eserver.org/30327.html The following is a brief description of how I tested a user manual for a word processing program to be used by low-level and intermediate-level users. http://tc.eserver.org/30320.html http://tc.eserver.org/30320.html We currently use a variety of software and hardware tools to do our work. Unfortunately, there isn't one perfect software package that does everything we need. http://tc.eserver.org/30340.html http://tc.eserver.org/30340.html Provide your boss and the personnel department with a copy of your resume each time you update it. They will be interested to learn about any educational or training programs you've completed, changes in your current job responsibilities, new professional or civic organizations you've joined and any technical skills you've acquired since starting your current job. A resume should also reflect special accomplishments and your on-the-job performance record. http://tc.eserver.org/30332.html http://tc.eserver.org/30332.html If you're a technical writer, writing an article and getting it published in a trade or user magazine is a good way to expand your capabilities, enhance your resume, promote yourself, and have fun. And if you want to establish yourself as an expert on something, there's no better way. http://tc.eserver.org/30308.html http://tc.eserver.org/30308.html Have you ever been working at the computer so long that your eyes 'went buggy?' Or so intensely that you could barely move when you got up? Working long hours at a computer may be more hazardous than you know. One real possibility is that you will develop Carpal Tunnel Syndrome (CTS). http://tc.eserver.org/30312.html http://tc.eserver.org/30312.html The technical contracting industry provides a unique career opportunity for experienced professionals in most technical communications disciplines. It also provides a possible alternative to unemployment in view of the continuing 'down-sizing' and restructuring activity going on in today's marketplace. http://tc.eserver.org/30311.html http://tc.eserver.org/30311.html Sexist language consists of various words and terms that foster stereotypes of social roles based on gender. Professional writers must keep abreast of significant changes in our language, and the issue of sexism is an integral change. Sexist language has become offensive. Sexist language is confusing. http://tc.eserver.org/30317.html http://tc.eserver.org/30317.html As a technical writer with above average organizational skill, you likely already keep your files in nice little subdirectories in logical little groups -- User's Guide illustrations here, research notes there, stuff for the service manual over yonder. But what if, in an instant, your files were all taken out of their subdirectories and put in one big directory? Could you distinguish one file from the other without opening them up? You can only assume that files with identical names disappeared. http://tc.eserver.org/30314.html http://tc.eserver.org/30314.html On projects for which you must produce both on-line and paper documentation, there are many things you should consider before you start. http://tc.eserver.org/30313.html http://tc.eserver.org/30313.html Documentation usability testing has been with us at least since 1983. But, to all intents and purposes, it seems that there is still very little testing being done. Of all the documentation quality assurance activities that we can carry out, usability testing represents one of the best values in the process chain. Without devaluing any of the other quality assurance functions, it is safe to say that money spent on usability testing is extremely well spent. http://tc.eserver.org/30310.html http://tc.eserver.org/30310.html With just a modest amount of equipment and effort, you can uncover some serious product glitches and potentially earn your company thousands of dollars and a sterling reputation. The first step is to get a video camera, a product prototype, and a small sample of your target audience. http://tc.eserver.org/30306.html http://tc.eserver.org/30306.html To make the most of limited opportunities, you have to distinguish yourself from the crowd of other technical writers who'll be vying for the same positions you're after. In other words, you have to go into that job market armed with more than just a bachelor's degree and some classroom writing samples. Following are some suggestions that can help you acquire some professional technical writing experience, broaden your skills and knowledge of the technical writing field, and get you over the entry-level hump. http://tc.eserver.org/30309.html http://tc.eserver.org/30309.html Rapidly expanding international commerce demands multilingual product descriptions and instructions for users. Technical products require precise translations by knowledgeable translators to avoid costly or even fatal errors. These may range from simple business letters to legal documents, patents, scientific articles, service or end-user manuals. http://tc.eserver.org/30316.html http://tc.eserver.org/30316.html Technical communicators will take on increasingly important roles as technology becomes ever more sophisticated. After all, we must be able to use this equipment once it is installed. http://tc.eserver.org/30305.html http://tc.eserver.org/30305.html Over the years, there has been much debate and discussion in the Society as to whether technical communication is a field, an endeavour, a profession or a discipline, none of the above or all of the above. The topics of professionalism, certification and accreditation have often appeared in the pages of Technical Communication and Intercom. I would like to take the opportunity to review the status of technical communication and to highlight the role of research in technical communication. http://tc.eserver.org/30307.html http://tc.eserver.org/30307.html They call us 'documentation specialists' in the biz. Our mail is addressed to 'doc spec' because 'documentation specialist' doesn't fit on mailing labels. At social gatherings, people's faces go blank when we say we write software documentation or computer manuals. But what are we, really? http://tc.eserver.org/30315.html http://tc.eserver.org/30315.html People who follow the right trends will someday lead them. Such an opportunity now lies in the hands of technical writers, as the computer field moves toward standardized, graphical, easy-to-use interfaces. http://tc.eserver.org/27112.html http://tc.eserver.org/27112.html Context-sensitive help systems often need redundant placement of information. This ensures that the information is seen by visitors who enter and move unpredictably through the system. Redundant placements take the form of descriptions, explanations, warnings, and the like that amplify other subjects. In software documentation, for example, some candidate subjects include the purposes of screens and tabs, the effects of selected options and significant functions such as Delete, and reminders of required access permissions and prerequisite steps or conditions. You can save development time and promote consistency by cataloging information so that it can be inserted wherever needed using your authoring software's copy and paste functions. http://tc.eserver.org/27110.html http://tc.eserver.org/27110.html Yet those of us who are fully sighted forget that as we make the Web our main information vehicle, we may be cutting out millions of customers or potential customers. And these millions (5 to 10 million in the U.S. alone, by some estimates) have every moral and legal right to have access to that information. http://tc.eserver.org/27111.html http://tc.eserver.org/27111.html e-Video is divided into four major sections: Opportunity, Production, Compression, and Delivery. Although these can (and must) get a bit technical to be useful, I found Alesso's style understandable. http://tc.eserver.org/27109.html http://tc.eserver.org/27109.html If you need to learn XSL, or think it might be a career-enhancing move, there are currently very few books that describe XSL. In fact, some of these books can be overwhelming in size and in programming detail. The XSL Companion is different, and, I feel, aptly named a 'companion'. http://tc.eserver.org/27114.html http://tc.eserver.org/27114.html As someone who has been working as a writer in the high-technology field for better than a dozen years now, I have been watching with interest and enthusiasm the slow convergence of the disciplines of writing, interface design, and engineering. In the design of integrated help systems particularly, the traditional boundaries for developing content, interfaces, and features have blurred—resulting in a collaborative enterprise that I refer to as infoneering. http://tc.eserver.org/27115.html http://tc.eserver.org/27115.html In today's market, corporations consider 'cost avoidance' a top priority; nonetheless, complex products and tasks still demand training. Therefore, organizations look for efficient and effective training methods. E-learning answers that search. http://tc.eserver.org/27113.html http://tc.eserver.org/27113.html The mentor relationship has been called the 'pinnacle of work relationships.' A mentor is more than a peer, more than a coach, even more than a sponsor. Mentors typically have influence within the organization or community. They use this influence to empower their protègès. The mentor relationship is really a partnership--the mentor provides guidance and opportunities, the protègè provides energy and a fresh perspective. http://tc.eserver.org/27108.html http://tc.eserver.org/27108.html Collaboration is a key element of the documentation process at SolidWorks Corporation, and it contributes significantly to the high quality of the technical documents. 'We couldn't produce the volume of documents that we do in the time that we have without working closely together,' says Georgia, manager of the Technical Publications department. Five technical writers and eight translators collaborate with each other, with developers and testers, with a translation house, and with a print house. Together they produce a user's guide, a tutorial, multiple online help systems, and numerous smaller documents with each release of the software. Releases occur about twice a year. Because each release includes major new functionality, the documentation schedule is very tight. 'Taking into account that we have to wait for the engineers to complete their changes, and that we have to freeze the English version in time for the translators to translate before the release,' says Georgia, 'the schedule is even tighter than it appears at first.' Some of the techniques that make this situation workable are an integrated hardware and software system, careful distribution of responsibilities, explicit procedures and style guides, and file maintenance. http://tc.eserver.org/10812.html http://tc.eserver.org/10812.html Some companies and upper management, and even some documentation managers and writers, seem to agree. After all, in today's world of desktop publishing, writers are also typesetters and illustrators -- why not let them be editors as well? They know English. So why not save money, terminate the editors, and let peer editing begin? Or if we do keep some editors, let them be the designers, illustrators, and typesetters. As for language? Forget it! The readers will understand. Besides, who reads documentation anyway?