Barriers and Approaches to Reviewing Documentation

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.

Boston Broadside (1997). Articles>Documentation>Editing>Collaboration

Becoming InfoWranglers: New Career Ladders and Competencies for Technical Communicators

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.

Carliner, Saul. Boston Broadside (2000). Careers>TC

Carpal Tunnel Syndrome

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).

Rollins, Cindy. Boston Broadside (1991). Articles>Human Computer Interaction>Biomedical>RSI

Cataloging Information Aids Help Development

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.

Barten, Alfred. Boston Broadside (2001). Articles>Documentation>Indexing

Contracting as a Career Alternative

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.

Randolph, Brett W.F. Boston Broadside (1991). Careers>Consulting>Freelance

Control Costs of Translation with Advance Plan

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.

McBride, Bill. Boston Broadside (1993). Articles>Language>Translation>Project Management

Creating Effective Translations

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.

Wright, Ami. Boston Broadside (1997). Articles>Language>Translation>Localization

Designing Your Web Site for the Blind

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.

Ball, Guy. Boston Broadside (2001). Design>Web Design>Accessibility>Visual

Review: e-Video: Producing Internet Video as Broadband Technologies Converge

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.

Boeri, Bob. Boston Broadside (2001). Articles>Reviews>Multimedia>Video

Every Noun Can Be...

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.

Allison, Nancy. Boston Broadside (1989). Articles>Writing>Diction>Grammar

Fixed Quotes and Broken Promises

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.'

Juillet, Christopher. Boston Broadside (1990). Articles>Project Management>Planning

Focus on Consulting: When Home is Where You Do Your Job

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.

Boston Broadside (1989). Careers>Consulting>Freelance

Forget About the Lawyers! First, Let's Kill the Editors! Right?

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?

Sorotskin, Marilee J. Boston Broadside (1991). Articles>Editing>Documentation

Review: Getting to Know the XSL Family of Standards: A Review of The XSL Companion

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'.

Boeri, Bob. Boston Broadside (2001). Articles>Reviews>XSL

Health Care Prescriptions for a Terminal Job

What do you do about medical insurance coverage if you are laid off?

Randolph, Brett W.F. Boston Broadside (1992). Careers>Unemployment>Biomedical

Help Needed

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.

Boston Broadside (1992). Careers>Writing>Technical Writing

Hidden Factors of Documentation Quality -- Part 1

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.

Sesnovich, Bruce A. Boston Broadside (1993). Articles>Documentation>Quality>Technical Writing

How Safe is the Data on Your Hard Disk?

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.

Varney, Gord. Boston Broadside (1991). Articles>Technology>Security

How to Plan On-line and Paper Versions of a Software Manual

On projects for which you must produce both on-line and paper documentation, there are many things you should consider before you start.

Kozuma, Bruce. Boston Broadside (1991). Articles>Documentation>Project Management>Planning

If You Want Something Done Right, Don't Do It Yourself

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.

Allen, Jennifer. Boston Broadside (1992). Articles>TC>Collaboration>Workplace

In Praise of Usability Testing

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.

Hosier, Bill. Boston Broadside (1991). Articles>Usability>Testing

Infoneering: Beauty and the Beast

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.

Sesnovich, Bruce A. Boston Broadside (2001). Articles>Writing>Technology

Interchange Keynote Presentation: E-Learning

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.

Gruener, Bill. Boston Broadside (2001). Articles>Education>Online

Leadership Through Empowerment

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.

Juillet, Christopher. Boston Broadside (1990). Articles>Management>Collaboration