Hart, Geoffrey J.S

Demonstrating the Value of Editing

Like all other technical communicators, we editors must sometimes struggle to prove our worth to employers. We know our value, and the more clueful of our authors understand, but sometimes it takes a bit more work to convince senior managers that we serve a useful purpose. Managers generally require specific examples, usually supported by hard numbers. In this article, I’ve provided a few random facts and figures that I’ve accumulated over the years that you can share with management.

When Statecraft Fails: Tips on Surviving the Great Game

Following up on his article in the September/October issue, Hart explores how to avoid “rats” in office politics and offers advice on combating coworkers who might not have your best interests in mind.

Editorial Ethics: The Role of the Editor Before Peer Review

Editors who work with authors before a manuscript is sent for review face certain challenges. Since we’re often the first to see a manuscript, we sometimes encounter problems we must help solve before they come back to bite the author. These problems fall into a variety of categories, of which I see three repeatedly in my work. In this article, I’ll discuss the nature of these problems, provide examples from my own career as a science editor, and suggest how similar problems might arise in other types of editing.

The Limitations of Mental Models

As human beings, we create conceptual models that enable us to understand the complex world around us. Hart believes that information designers should understand mental models as a tool for creating the best possible communications.

Typography 101B: The Role of White Space in Making Words Readable

Hart continues his dissection of typography in this second installment, in which he discusses the important of spacing for the readability of words and sentences.

Why Certification by the STC Won’t Work

The virtues of certification cannot be ignored, but they are outweighed by the drawbacks: There’s no evidence that employers will value certification; it can be highly subjective; and it requires ongoing renewal, even for experienced practitioners, to avoid diluting its value. The more important task must be to demonstrate our value to employers. Only once they understand our value will certification provide a means to assure employers that they can expect to receive that value.

Implementing Onscreen Editing: A Four-Step Process

Four technological or organizational barriers interfere with change, each leading to an implementation step. To overcome resistance to change, harness the energy of existing processes rather than trying to fight them.

Inspiring Reviewers to Review Your Documents

To obtain good reviews, you must make the process as painless as possible for reviewers.

Ten Technical Communication Myths

Technical communication has accumulated its share of mythical rules of thumb, but the good news about our profession's myths is that they too contain grains of truth and insights into things that are truly important to us. (This work is a reprint of http://tc.eserver.org/10500.html, but not locked for STC members only.)

The Economics of Membership

Members often ask what advantages they receive for their membership dollars. The answer is so obvious we sometimes fail to see it. With apologies to the kind souls at MasterCard, a few thoughts on the value of your STC membership.

Much Ado about Nothing, Part 2: Deconstructing a Page

In a continuation of his January column, Hart sheds some light on page layout and design—and gives color to a seemingly “black-and-white” concept.

Much Ado about Nothing, Part I: The Importance of White Space

White space is a paradox: by definition it contains no information, yet it clearly communicates despite lack of content. Hart describes how to incorporate white space into the information design process.

Reader-Centered Documentation Provides the Necessary Context

A features-based approach to documentation is appropriate for reference manuals, where the goal is to provide information on something the reader already knows. This article explores how to meet the needs of the reader when providing documentation for user manuals.

Bridging the Gap between Cultural Studies Theory and the World of the Working Practitioner

Cultural studies is an academic field that focuses on understanding the unchallenged assumptions that constrain and shape communication and related interactions among people. Although the field has made considerable progress in the last half-century, many practitioners have either never encountered the field, or have encountered it only through extremist advocates who do the field a great disservice. As a result, they have lost the ability to benefit from the insights provided by cultural studies. In this paper, I review the recent book Critical Power Tools to provide an update on the current thinking in the field, and to demonstrate how the modern form of the field has much to teach technical communications practitioners who are willing to listen to what the theoreticians have to say.

Hierarchies in Online Information: Balancing Depth and Breadth

Hart explains how understanding hierarchies--the order in which information is grouped--can help you choose an appropriate balance between the depth and breadth of your online information.

Bridging the Gap between Cultural Studies Theory and the World of the Working Practitioner

Improving Your Editing Efficiency: Software Skills, Soft Skills, and Survival Skills

Editing efficiently involves a mix of software skills, soft (human) skills, and strategies for surviving chaos. Although software skills are certainly important--we never have as much time as we need, and computers really can help--we must still nurture author-editor relationships. Knowing the strategies battle-scarred editors have developed over the years can save you from duplicating those scars. In this paper, I'll discuss the software skills you'll need to work efficiently, how to cope with the human factors involved in editing, and some strategies for managing the often-chaotic editorial life.

Surviving a Busy Year: The Marathon of Chapter Presidency

Every year, the annual conference offers potential chapter leaders a session entitled 'The Marathon of Chapter Presidency'. They're not kidding. My year as president of STC Montreal was a long, steady, exhausting haul--but a very pleasant one now that I can look back on our achievements. In this paper, I'll pass along tips learned from other presidents and tips I learned while coping with my own duties. Try out as many tips as your time, energy, and volunteers permit!

Mental Models: Laying Foundations to Support Readers

Technical communication is often no more complicated than clearly describing the steps in a procedure, but sometimes we must create new models for each key part of a complex procedure.

Combining the Print and Online Media Offers Synergies

Companies had decades of experience in using printed materials to persuade readers to contact them, whether by phone, mail, or in person. This model of interaction with customers had worked so well and so predictably that we simply moved it online, largely unmodified. That was by no means wrong, but as Web technology and our comprehension of that technology both evolved, the approach proved limiting.

Content is King

Not all content is created equal. In fact, the real issue isn't the primacy of content, since no user in their right mind will come to stare at a blank screen labeled Me.com; the real issue is what type of content you're offering.

Dr. Strangemeeting (or: How I Learned to Stop Worrying and Enjoy the Donuts)

Experts claim you'll spend 1500 hours in meetings during a typical 30-year career--that is, if you can duck some meetings by looking busy and if you can retire early. If you duck slowly or plan a long career, you could easily spend more time in meetings than you spend working. Fortunately, a little planning and some quick thinking should let you turn meetings into a blessing--or at least a tolerable evil.

Hockey and the Art of Technical Communication

If STC would fund an appropriately intensive study of the NHL, I have no doubt we could inspire dramatic changes in technical communication; the contrasts between the NFL and NHL approaches have profound consequences for our work.

A Millennial Paradigm for Documentation: the Scroll!

Although some zealots have proposed eliminating printed information entirely in favor of online help systems, Adobe Acrobat files, and even e-books, discarding printed books may prove less effective than simply modernizing them. Scrolls are the logical successors to books.

The Physics of Reviewers

Subject-matter experts, managers, and other reviewers tenaciously resist our nagging to review documents properly, often delaying reviews until it's too late to do a good job. It's not that they inherently oppose quality control; rather, the problem's in the amount of work required to review something thoroughly, and 'work' is a physics concept. Conveniently, reviewers--like falling objects--follow the same laws of physics as the rest of the universe, and understanding those laws helps you predict reviewer behavior and take appropriate countermeasures.

Policies, Procedures, and Paralysis

We live in an uncertain world, and good intentions are no guarantee of success, so we develop policies and procedures to provide ourselves with a measure of security and provide the illusion of control.

Privacy Means Never Having to Say You're Sorry

For those of us who work with computers, the value of identifying ourselves to Web sites is increasingly obvious: no more retyping our name and address information, less need to memorize dozens of log-in passwords and paths to specific Web pages, less spam, and fewer irrelevant banner ads. But even those of us who appreciate the value of sharing some personal information with Web sites and those who run them are growing increasingly uncomfortable with the potential for abuse inherent in having information on our identities and preferences broadly available.

Reach Out and Touch Someone

The hardest part of communication lies in the many options we have available, and how tricky it can be to pick the right option for each individual member of our audience. When we write something, whether in print or online, we try to produce something that satisfies as many readers as possible because we require a 'one size fits all' solution: we're not physically present to tailor our approach to meet each individual's needs, and so must meet a range of needs in a single document. With print, we're stuck with static text: the text can't change until we rewrite it and distribute a new version. Moving information online makes it easier to revise and distribute information, but actually updating the information still requires a writer. Are there alternatives that make it easier to reach customers with our messages?

Taking Advantage of Reflexive Responses

None of us likes to admit that we have conditioned reflexes that override our higher cognitive abilities, yet such denials notwithstanding, each of us does occasionally respond without thinking something through clearly. As technical communicators, it's important for us to accept this fact of human nature and plan for it in our documentation, and to work with the developers of the products that we document to both take advantage of the helpful reflexes and find ways to ward off the harmful ones.

Wash Your Hands After Reading This Manual

The next time you complain about the usability of your computer, think of this: despite patently suboptimal design, Windows computers are really no more difficult to use than your washroom, and the washrooms have been around for an awful lot longer. The bottom line--you should pardon my choice of words--is that despite manifest flaws in both technologies, each lets you accomplish surprising quantities of work. And technical writers take heed: this appalling gap in end-user documentation could just be the next million-selling 'for Dummies' book.

Defining Editing and the Top Five Rules

Do no harm: this means no harm to the author's intended meaning, reputation, or legal liability; no harm to the reader, such as by omitting necessary safety information; and no ethical harm, such as by knowingly distorting the truth.

Documentation is a Profit Center!

Everyone knows that documentation is a cost center, and that downsizing writers and moving documentation online save money. Unfortunately for 'everyone', it's trivial to demonstrate that documentation is actually a profit center--and we don't even have to wrassle with messy stuff like customer satisfaction to prove it.

The Domino Effect: Changes Have Unforeseen Consequences

It's obvious that almost all the changes you make will affect your user community, but considerably less obvious how helpful that community can be about providing feedback before you make the changes.

Don't be a Researcher: Be a Finder!

One of the fascinating things about science is just how many breakthroughs have come from mixing the knowledge provided by entirely different disciplines, and I suspect that this lesson has yet to be learned in our own discipline of scientific communication. Technical writers have been grappling with the issues of rhetoric, audience analysis, and usability testing for years, and have developed effective solutions and techniques for addressing these issues. Scientific communicators have largely ignored these breakthroughs and clung to our familiar models of communication.

Don't Wait to be Downsized!

Sure, the economy's booming now, but as the Asian crisis becomes the North American crisis, it pays to remember Newton's famous law of gravity: what goes up must come down again. And, of course, when the economy comes down and pension fund managers start asking those awkward questions about why they should remain invested in your company's stock, managers have a lemming-like tendency to trim staff to make room for short-term profits and long-term plausible deniability. As a technical communicator, you're obviously well up on the hit list, which some might see as a bad thing--but there's a silver lining to every cloud (or, in our case, a copper lining; they don't pay us well enough for silver). In fact, the good news is that it's easy to ensure you're the first one fired, so you can leave before the job becomes mundane without looking like a quitter. Then there are all those perquisites (severance pay, a little downtime)...

(e)Xpressive Markup Language?

Conveying the emotional tone of a Web page has, up until now, been impossible with HTML, and the XML standard fails to address this issue. As an interim solution, developers have proposed several new tags to the World Wide Web Consortium (W3C).

The Editor as Translator (or: How Do You Say That in Calculus?)

Sometimes English just isn't the most elegant way to say something. It might be so much easier if we write for a math journal, because the correct language for the explanation can be, in fact, mathematics.

Estimating Project Times and Costs Without Losing Your Shirt--Or Your Sanity

Determining how long it takes to complete a job is essential for planning and for budgeting your time, whether you're a wage slave or a freelancer. In this article, I'll focus on the needs of the freelancer, but the same approach will work equally well for managers of teams of technical communicators and even for lone writers.

Garbage In, Garbage Out: Using Affordances

The trick is to make data-entry forms clear enough that workers understand what you require of them without having to ask. This understanding alone can drastically reduce the frequency of errors, but to turn that understanding into a payback, you'll have to design a label for each field that is truly obvious to the workers. Information designers call these clues "affordances", and if you're lucky enough to have technical writers or editors in your organization, you can probably enlist their aid in designing these clues.

Good Times, Bad Times

The first 'macro viruses' attached to Microsoft Word documents emerged within weeks after Office 97 was released, and sounded the warning that a new era was upon us.

If You Build It, They'll Come

If you create a community around your Web site, look beyond providing the outer semblances of community: design a site that can potentially work the way each of these very different members of the community wants it to work.

Indexing Web Pages: Maybe Books Aren't Such a Bad Model After All!

One of our favorite cliches is that you can't use the printed book as a model for online information. Web-based information, which is following the same evolutionary progress as online help systems, has inherited this 'books are bad' philosophy. However, any statement we've begun to take for granted bears some re-examination, because unquestioningly accepting dogma undermines our efforts to improve communication.

The Information Revolution

Nobody is offering courses in how to prepare hypermedia, nor are there a large number of jobs available for hypermedia authors. As we begin to come up against the limits imposed by the volume of existing knowledge, we will eventually be forced to place more importance on managing our information explosion.

Mail Your Newsletter with Less Labor and Cost

A lot of STC chapter and SIG mailings are done the old-fashioned way: envelopes stuffed by hand, and stamped manually or--occasionally--with a stamp machine. That's an awful lot of work, and expensive too. When I confronted this problem a few years back for my current employer, some research revealed a solution that eliminated the annual pressganging of volunteers to stuff envelopes and also saved us a fair bit of money.

Measure Twice, Cut Once

Acting without planning can be expensive, and because of the potential cost of poorly thought-out actions, we should not only plan, but plan twice.

The Needs of the Many

Installing major software patches or upgrades ranks right up there with paying your taxes in terms of stress. Why the stress? Well, first, there's the instinctive fear of screwing up something that's already working reasonably well, thank you very much, and spending the next 60-hour week trying to get back to where you were before you 'improved' things.

Notes on the Documentation Development Process

Define your audience, and their needs, explicitly and carefully. The definition process may lead you to include additional material such as indexes, system requirements, and contextual notes (e.g., lists of exceptions), as well as the preplanned documentation.

Nurturing a New Writer

Technical communicators represent one of the most mobile groups of professionals I'm aware of, with some sources claiming that the average time between changing jobs is as low as four years. This means that many of us will soon find ourselves in the position of working with newcomers, whether permant staff or 'temps,' and this means we may face the problem of how to mentor or supervise someone new to our workplace. This article discusses how to work with someone who already has the basic training, but is nonetheless naive in the ways of your particular organization.

Science and Fiction

The purpose of this article is to clarify some common misperceptions as to what science is, what science does, how science relates to technology, and how the activities of science and technology differ from the areas of informed and uninformed speculation, and how the three areas complement each other.

So You Want to be an Editor?

Most technical communicators are hired primarily as writers and creators of information, but despite this, many of us must learn how to edit at some point. Whether the reasons are good (to prepare better first drafts for review) or bad (your employer won't pay for a full-time editorial position), the reality is inescapable: at some point you're going to have to edit your own writing or that of a colleague. The problem is that editing requires an entirely different mindset than writing, and it's difficult to make the mental shift from creating to revising.

Sometimes Playing Dumb Makes Things Work Better

I've learned how to forget for a period of time that I know almost as much as my authors about their subject, and this lets me play dumb and trip over things that the author's peers and I could both figure out with a little work--or a lot of work, occasionally. Once I understand why I tripped over a particular wording, I can figure out how to fix it so that nobody else, even if they really were as idiotic as I sometimes pretend to be.

Sometimes You Really Can be Too Helpful

It's important to establish and maintain relationships with your audience: it gives you a handle on their changing needs so you can continue to meet those needs.

Teamwork and the Product Documentation Process

Get to know your new teammates. Get to know your audience. Define the product's features. Create a mockup of the user interface. Begin to document the features and interface.

Using the Triage Method in Technical Writing

Pragmatism is the necessary first step: do the best job you can do under the conditions. Nobody's going to benefit if you do a superb job on half the manual, then die of stress before you can document the important parts in the second half.

Validity Checks

Work with your fellow employees to understand how they enter data so you can determine the best way to present their choices; they won't forget who's responsible for their improved accuracy and speed, particularly around performance appraisal time. Of course, you'll also earn your own manager's gratitude once you're no longer wasting time fixing preventable errors.

Writer-Editor Relationships in Revisions

Editors, professional or otherwise, can be annoying individuals. The trick is to focus on the helpful parts of that annoyance and try to ignore the less-helpful parts.

The Myth of "The User"

Instead of becoming computer users, like the cheery protagonists of Star Trek, we've become the computer used, like the gloomy inhabitants of Dilbert.

Is "Intercultural" Communication a Moot Point?

Good writing is good writing in any language, and focusing on the quality of the writing in your own language is a great start to any communication with people from other cultures.

Personas and the Technical Communicator

What's the problem with personas? They're a new concept to many communicators, and thus sufficiently unfamiliar to make them difficult to use. To help solve this problem, I developed a couple of personas to show you how it's done, and illustrate their implications for documentation.

Finding Work in Tough Times

It's not easy to find rewarding work. Hart describes three steps you can take to help the process go more smoothly when searching for that new job.

Abstraction: Making the Complex Easier to Understand

How can we make difficult concepts easier to grasp? Hart explores abstraction and how it can be used to clarify both simple and complex ideas.

Effective Outlining: Designing Workable Blueprints for Writing

Save time and increase your credibility by creating an effective outline. Hart's article discusses three important steps in designing an outline.

Microwriting: Small Choices with Large Implications

The little elements of writing can make a big difference. If you're looking for a way to refresh your writing, consider paying close attention to the aspects involved in microwriting.

Designing an Effective Review Process

Review processes can easily become frustrating and complicated. Hart shows how to create and revive a review process that can be tailored to the needs of your situation.

Technology and Knowledge Transfer: Science and Industry Working Together

Science and technology are intimately related. The technology sector that drives the modern economy would never have arisen without basic scientific research, and that research is now being funded by companies seeking to gain a technological edge over their competitors. Despite this mutual dependence, technical communication has taken different paths in science and industry. Technology and knowledge transfer, the communication of research results to an audience that can implement the results, bridges these two solitudes and strongly resembles much of the work done by other technical communicators.

Recipe for Designing Usable Documentation

What makes documentation usable? Usable documentation accommodates the way I think. Hart summarizes his principles for define 'user-friendly documentation.'

Sensitivity to Other Cultures

Shares experiences and observations collected from working with colleagues in Asian cultures. Discusses the importance of actively working to accommodate the needs of communicators from other cultures by beginning the dialogue in their language.

"Backing Up" Doesn't Mean Retreating

Recently, several friends and colleagues have lost important files as a result of viruses, power failures, computer crashes, and miscellaneous other disasters that accompany working with computers. Each person could have minimized the consequences if they had developed and rigorously followed a simple backup strategy for their data. The fact that this happened to experienced computer users in each case leads me to believe that data loss is symptomatic of a broader problem: As technical communicators, our tight focus on documenting how to use a product sometimes makes us forget to document the consequences of using the product.

Avoiding Repetitive-Stress Injuries: A Guide for the Technical Communicator

Writers and editors in particular put in an awful lot of miles at the keyboard every day. For example, I commonly spend a solid 8 hours typing. Writers and editors in particular put in an awful lot of miles at the keyboard every day. For example, I commonly spend a solid 8 hours typing. Then there's that darned mouse. W. Wayt Gibbs, writing in the June 2002 Scientific American, used the Mouse Odometer software (www.modometer.com) to monitor his habits and found that in a single 5-day period, he'd recorded 2440 feet of mouse movement and nearly 22 000 mouse clicks. It's no wonder computer users sometimes experience serious physical problems.It's no wonder computer users sometimes experience serious physical problems.

Prescriptive Audience Analysis: Moving Beyond the Purely Descriptive

Editing and writing both require an understanding of our audience, because without that knowledge, we can't shape our words to help them easily grasp difficult concepts. To understand our audience, we do what all writers and editors do, whether consciously or unconsciously: We create an image of our audience that guides our choice of words, images, and metaphors. This image is variously known as a 'stereotype' (e.g., Schriver 1997) or a 'persona' (e.g., Graham 2001). Keeping that image in mind as we work helps us satisfy the reader's needs, but if we're not careful, it can also cause us to waste valuable time collecting information that doesn't really help us communicate.

Looking for Work as a Scientific Communicator?

Many technical writers recently found themselves looking for work in the wake of September 11th and the dotcom meltdown.

Streamlining an Interface Using Information Design Principles

Describes a process for improving interface usability.

Don't Feed the Subject Matter Experts

I found myself wondering; was there any statistically significant relationship between feeding and cooperation?

Scientific Documentation: Learning from Journal Articles

Suggests that writers of technical manuals could learn a thing or two about usability from the consistent form of scientific journal articles.

Editing Web Pages: A Second Look

How to edit Web pages--with revision tracking--using Microsoft Word.

Taking Advantage of "Automatic Text" Features

I recently began looking for a way to eliminate the need to manually perform small repetitive tasks. In Microsoft Word, that way is through the software’s 'automatic text' features: Autoformat, Autocorrect, and Autotext. In this article, I’ll focus on these features in Word, but will also discuss how to lighten the work load in other software.

PowerPoint Presentations: A Speaker's Guide

Vinton Cerf, one of the founders of the Internet, reportedly parodied the well-known quote about the cost of attaining power, observing that if power corrupts, 'PowerPointcorrupts absolutely.' Pointed though Cerf’s statement is, it places far too much blame on the software. After all, speakers must take some responsibility for their presentations. As in any other form of communication, you must decide what you’re going to say and how you plan to say it. But once that’s done, you need to use all the skills at your disposal to make the chosen medium work for you.

Speaking in Tongues: Dealing with Word's Dictionaries

Word has powerful language tools, but if you don't understand how they work, even a simple spellcheck can pose problems. In this article, I'll discuss how to take full advantage of Word's language settings.

Implementing On-Screen Editing

On-screen editing offers obvious advantages over paper editing, including greater accuracy, shorter turnaround times, and improved consistency. Because authors don’t have to retype handwritten edits, there’s less risk of misreading or missing corrections. Moreover, the edits have already been typed and spellchecked, so no new typos are introduced. Most editors can also enter corrections faster with a keyboard than with a pen, particularly when complex edits require restructuring of the document or extensive rewording, and eliminating the retyping phase further reduces turnaround times. Last but not least, using the search tools makes it easier to achieve consistency in long or complex documents.

A Programming Primer

The easiest way to gain the respect of programmers is to learn to speak their language. If you can do that, they’ll inevitably recognize the effort you've invested in learning to appreciate their work and will treat you as an equal thereafter. With that goal in mind, I present this glossary of key programming terms you should master.

Overcoming Objections to Onscreen Editing

Although onscreen editing has been available for many years, it remains underused in many workplaces. Editors offer many reasons for their reluctance to embrace this technology, and by understanding these reasons, it becomes possible to mitigate the problems and help editors begin using the technology. By doing so, managers can implement a process that is more efficient for both the editor and the authors being edited.

Streamlining an Interface Using Information Design Principles

'Information design' is the art and science of understanding problems from the product user's standpoint, and using that understanding to select an appropriate mix of graphics and text that supports the design and presents necessary information appropriately. This progression topic presents a simple, iterative way to examine a design problem, and uses that approach to solve a common design problem (using space more efficiently in a software interface).

Avoiding Repetitive-Stress Injuries: A Guide for the Technical Communicator

Writers and editors in particular put in an awful lot of miles at the keyboard every day. One serious problem is the risk of so-called 'repetitive-stress injury' (RSI)--simplistically, any injury that results from overuse of a body part without giving it time to recover. In fact, 'overuse injury' is probably a more immediately obvious term, and given how much time many of us spend using computers, overuse is indeed a risk.

Just the FAQs

Offers advice on creating effective FAQ documents.

Getting Involved in Interface Design

Describes a four-step process to help technical writers gain influence over product design.

Designing a Telephone-Based User Interface

Explains how technical communicators, drawing on their experience designing Web sites and software interfaces, can help design effective interfaces for telephone-answering and call-routing systems.

Practical and Effective Metrics

Discusses several issues involved in developing metrics that measure performance and identify specific problems affecting performance.

Practical Tips for Improving Web Site and Intranet Usability

There's a large body of theory available to guide Web and intranet design, but concentrating too much on theory sometimes leads designers to overlook basic things they can do to improve the usability of sites. This article presents, in no particular order, seven simple ways to make your Web site or intranet more usable.

"Prescriptive" Audience Analysis: Moving Beyond the Purely Descriptive

Editing and writing both require an understanding of our audience, because without that knowledge, we can't shape our words to help them easily grasp difficult concepts. To understand our audience, we do what all writers and editors do, whether consciously or unconsciously: We create an image of our audience that guides our choice of words, images, and metaphors. This image is variously known as a 'stereotype' or a 'persona'. Keeping that image in mind as we work helps us satisfy the reader's needs, but if we're not careful, it can also cause us to waste valuable time collecting information that doesn't really help us communicate.

Audience Analysis: Looking Beyond the Superficial

In performing an audience analysis, it’s easy to focus on simple, obvious issues such as the differences between men and women. In fact, men and women have more similarities than differences when it comes to most of the things that technical communicators document. A discussion of some seemingly obvious differences between men and women illustrates how to look beyond superficial issues to find the truly important differences.

Technology Transfer: Science and Industry Working Together

Science and technology are intimately related. The technology sector that drives the modern economy would never have arisen without basic scientific research, and that research is now being funded by companies seeking to gain a technological edge over their competitors. Despite this mutual dependence, technical communication has taken different paths in science and industry. Technology transfer, the communication of research results to an audience that can implement the results, bridges these two solitudes and strongly resembles much of the work done by other technical communicators.

Structure Paves the Way Online

What I've called structure in this series actually has various other names, the most familiar of which are probably 'hierarchy' or 'information architecture.' Whichever word you use, structure encapsulates the relationships between the components of a site that visitors will use to navigate to the information they seek. Structure is simple enough to define, but can be devilishly tricky to create. A successful site structure must create what psychologists refer to as a schema: A mental model that visitors can use to understand where you've hidden the content.

Successful Online Presence: Relevance

'Relevance' means the ability of a site to present information that satisfies the visitor's immediate needs; if it doesn't meet those needs, then it's (by definition) irrelevant to that visitor. Obviously, our goal in designing a site is to make its content as relevant as possible to visitors. The key to understanding what makes something relevant lies in recognizing that relevance is never a static, unchanging aspect of the content you provide: Some things must change regularly and some must stay the same, but some may fall into both categories at different times. Knowing which information falls into each category, and when, can be tricky, because it relies on sound knowledge of the people who will be using your information and whose needs you'll be satisfying. Unfortunately, those needs change.

Editing Tests for Writers

Times are hard, and many former writers are pounding the dirt looking for work. Some who have extensive experience with peer review or revising documents are expanding their job searches to include careers as editors. However, new editors often face a barrier to entering the profession: the editing test. Rather than taking a chance on unproven candidates, publishers and other clients typically ask would-be editors to review short documents that test three main aspects of an editor’s skills.

Editing Web Pages

Investigates some of the specific issues involved in editing Web sites, an increasingly common task for us wage slaves and an enormous opportunity for freelancers.

Internet Resources for Editors

This month, I’ll depart slightly from my usual topic and focus on onscreen practices that aren’t actual edits—but that support activities such as fact-checking that we must perform while editing. Specifically, I’ll describe how to use the Internet as a research tool to improve the quality of your editing.

Keyboard Shortcuts and Other Tricks

This column focuses on using a computer to increase the effectiveness (both the productivity and the quality) of editing manuscripts, with an emphasis on tools and techniques rather than issues of grammar and usage.

Devil's Advocate

The problem with wearing the technical support hat, I discovered, is that it tends to slip over your ears. Over time, you stop hearing the shrill cries of the users you're supporting, then you stop listening so carefully, then you stop speaking the same language as they do. And since you're busy putting out fires all over the building, who has time to start listening again? Problem is, once you no longer empathize with 'them,' you forget that they've got their own unending stream of crises to deal with. But if you want to tame those devils, you're going to need to take the time to understand their needs as well as you understand your own, and find a solution that meets both sets of needs. More often than you'd suspect, the result is a win-win solution.

The Style Guide is 'Dead': Long Live the Dynamic Style Guide!

Nobody, least of all an editor like me, would argue that printed style guides are really dead--at least not in the sense that they're no longer with us and no longer useful. Yet there's no doubt that printed style guides are looking a little antequated these days. Despite how useful the guides are to writers and editors, they're simply too static for most writers, and don't take advantage of computer technology to make the writer's working life easier. But if you're thinking that online style guides are inherently better solutions, think again; using the computer to find static information certainly helps, but simply moving a paper guide online only exchanges one form of 'static' for another.

Automating Your Edits

Suggests several uses of Microsoft Word's macro capabilities to help editors improve their speed and consistency. Macros, for example, are customized keystroke commands.

Editing with Style (Sheets)

Offers editors tips on creating and using style sheets.

File-Exchange and Workflow Issues

Suggests ways that editors can organize multiple versions of articles and avoid the pitfalls of transferring electronic files over the Internet.

Getting Reviewers to Review

Presents ten humorous suggestions for technical writers on how to persuade reviewers of documentation to do their jobs.

Prove Your Worth!

Describes ten arguments technical writers can use to demonstrate their importance to their employers.

Seek and Ye Shall Find--And Replace

Offers tips on using search and replace commands in word processors.

Shakespearean Technical Writing

Shows how technical writers can make better use of literary devices such as metaphor and foreshadowing to produce better, and more enjoyable, documentation.

Spelling and Grammar Checkers

Provides a few suggestions about how writers and editors can use spelling and grammar checkers more effectively.

Why Edit On Screen?

Provides a thorough introduction to the practices of on-screen editing, including how to make corrections, insert questions and suggestions, and communicate the results to the author.

Nostradamus the Technical Writer

Sue Gallagher, a longtime technical writer, once posed the following riddle: 'How are science fiction writers like technical writers?' The answer, of course, is that both professions write about things we imagine will happen in the future, but that often don't--as anyone who's documented software or hardware for a startup company can confirm. With the new year arriving soon, I find my thoughts turning to a different form of science fiction: Eschatology, the art of predicting the future. It occurs to me that the role of technical writer as prognosticator has a proud history, and one that dates back to the days of Nostradamus the Prophet, one of the most famous eschatologists.

Cheating the Quality Triangle

Hart discusses ways that technical communicators can simultaneously improve the quality of their documentation, increase the speed with which it is produced, and lessen the costs of producing it.

Effective Interviewing: Get the Story

In this article, Geoffrey Hart offers the following tips on how to interview a subject matter expert (SME) for reliable, comprehensive, timely information:

Identifying Additions and Deletions, Part I: Using Compatible Software

Hart describes the problems and possibilities of Microsoft Word's Track Changes feature.

Identifying Additions and Deletions, Part II: Incompatible Software

Hart describes the difficulties of viewing electronic edits when the editor and the author are using incompatible software, and offers tips for working around these difficulties.

Special Needs: Editing Tables and Graphics

Hart explains the difficulties of editing tables and graphics on-screen.

The Style Guide is Dead: Long Live the Dynamic Style Guide

Arguing that printed style guides are too static to be useful, Hart recommends using a dynamic style guide, a system of templates, macros, and reference materials that actually guides writers through their work. The article also advocates direct interaction between editors and writers as a non-technical approach to a dynamic style.

Substantive Editing: Break It to Them Gently

Emphasizing the need for clear, polite communication between editors and authors, Hart demonstrates how editors should address imprecise wording, ineffective organization, and other substantive issues.

Conquering the Cubicle Syndrome

Cubicles aren't really physical walls--they're a state of mind. In effect, it's the belief that you've been compartmentalized and isolated that defines the cubicle. The four-sided, felt-lined livestock pens loved by evil office managers everywhere hides the truth: cubicles are all about being isolated and treated as part of the building infrastructure, whatever the physical location of your chair.

Dealing with Difficult Employees in the Technical Communication Workplace

Some of the more intractable problems we face on the job are the human ones. But cranky though Microsoft Word often seems, most of its blowups are at least predictable; humans are anything but. The worst problems can arise when you find yourself in a situation where power relationships come into play, which is often the case when you're managing another employee and responsible for their work and their on-the-job behavior. For a variety of reasons, technical communicators are often seen as 'difficult' or 'problem' employees--this means that co-workers tend to complain about us and insist that our managers correct our behavior. Unfortunately, we often work in high-stress environments that make it difficult for us to work calmly and difficult for colleagues to work with us peacefully. Many communicators complain that developers and other subject matter experts (SMEs) don't bother to understand what we do and thus, don't respect our work. As a result, they often consider meeting their own deadlines far more important than helping us do our work, and when we must ask them to provide the information we need to complete our documentation or to review draft documents, we don't get what we need. The result? We're forced to nag, and that can get us labeled as problems, not colleagues.

The Five W's of Online Help

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.

Top Five Tips for Starting a New Job

This article offers five tips that can help you get off to a good start in your new job.

A Day in the Life

If it's a good day, you arrive at work around seven o'clock, grateful for having missed the morning rush hour. Today's not a good day, so instead you crawl out from under the shakey shelf in your cubicle, glad that neither your cranky, obsolete computer nor the stale glass of Jolt cola fell on you during the night. Don't laugh; it's happened before, and putting yourself back together again cost you an hour of sleep you desperately needed. You smell the stench of cold pizza, and what's really appalling is that you're not sure whether it's coming from your shirt, your breath, or a hidden cache somewhere in the cubicle under piles of documentation someone left you to review. That's not your problem right now.

Content, Structure, and Relevance: The Ploy's the Thing

Attracting and retaining an audience on the Web requires the skills of a playwright, and like a good playwright, you have to be able to skillfully combine three inseparable elements: Content, structure, and relevance. Content is one of the hot buzzwords of the new millennium. Without content, your site can be aptly described by MacBeth's despairing lament: 'A tale told by an idiot, full of sound and fury, signifying nothing.' (Substitute 'Flash and Shockwave' for 'sound and fury' and you've got the picture.) Despair describes the second of these three components, because if you don't create a site structure that helps people find all that fine content you've created, they'll give up and go elsewhere--or go mad with the effort of searching, with results every bit as tragic for your job prospects as 'the Scottish play' is reputed to be for actors. And the part about 'signifying nothing'? If the content that visitors do eventually find isn't relevant to their needs, they're not going to come back any more than Lady MacBeth will.

Designing for the Other Half

Whenever we design something, we confront the problem of how to account for differences in our audience's needs, skills, and background. We accept that audiences are diverse and include people with widely varying skill levels, physical abilities, background knowledge, and cultural differences. They range from power users--who could teach us something about the product--to the greenest of neophytes. Some have significant visual or other limitations. Some can understand the most abstract concepts, whereas others wouldn't recognize a metaphor if it bit them. And some come from very different cultures, such as the gap that divides Macintosh and Windows users. Unfortunately, our knowledge of the more obvious differences sometimes leads us to make ridiculous assumptions, such as considering women and men to be different audiences, or believing that it's impossible to produce something that works equally well for experienced and new users.

Nothing but .Net? Nyet!

Given Microsoft's track record, it would seem awfully foolish for me to bet against them and those who will follow their lead, and the idea does seem superficially reasonable. But despite this, I predict that the ASP aspects of .Net won't work nearly so well as Microsoft hopes and may even fail outright. The problem with Microsoft's ASP approach? The strategy is driven more strongly by economics and a fear of competition from smaller, more nimble ASPs than by customer needs and habits.

Hart’s Law: The Magical Number Three, Plus or Minus Zero

George Miller, infamous for his 'magical number seven, plus or minus two,' somehow missed an even more important principle of how the world works: no matter how clever we think we are, it still takes us three tries to get anything approximately right. Although most of us have proven beyond a shadow of doubt our ability to blunder around and take many more than three tries, the overwhelming majority of us get it nearly right on the third try.

Privacy Means Never Having to Say You're Sorry

For those of us who regularly visit certain Web sites, the value of identifying ourselves to those sites grows quickly and painfully obvious: Accepting cookies from a Web site could potentially eliminate endlessly retyping our personal information, memorizing yet another login password, repeatedly re-customizing how a site responds to us, and enduring irrelevant information such as untargeted banner ads. But even those of us who appreciate the value of sharing personal information with Web sites and their designers have grown increasingly uncomfortable with the potential for abuse inherent in having confidential information about our identities and preferences broadly available. Even if a site isn't cracked and our private information stolen--always a risk on the Web--the site owner is bound to sell the information to commercial mailing lists, thereby guaranteeing us a lifetime supply of junk mail. Worst of all, we won't even be able to burn that junk on cold winter nights to stay warm.

Reach Out and Touch Someone

Providing the right combination of options for each individual member of our audience through a single online document (or online document set) would be tricky indeed, but consider the potential of being able to do so--the potential for providing flexible information. Users could quickly obtain the information needed, in the medium that suits them, with the appropriate level of detail right at their fingertips. An unobtainable utopia? Perhaps not.

Nobody Reads Manuals, Do They?

We technical writers have a mantra that we mutter quietly whenever someone asks an obvious question about how to use our software: 'RTFM.' But though Reading The (ahem) 'Fine' Manual would often solve the problem--assuming the purchaser actually received one of those increasingly rare printed manuals with the software--only technical writers seeking inspiration on how to do their own jobs better can be relied upon to read product documentation. To make matters worse, many of us admit that we'd rather play with a product, hoping to figure out what to do, than use the documentation.