From Marketing to Methodology: Writing in a Technology Company

By Dave Wright | Member and Harry Calhoun

Writers and editors who work for technology companies have to acknowledge the challenges, limitations, and opportunities that writing about technology bring. Some writers have a “pure” writing background but have to pick up the technological part as they go along. Others might have more of a technological bent but have to learn how to craft their writing to accurately describe the products and services of a “techie” company.

In this article, two writers examine the rigors and unique aspects of writing within a technology-based company. Harry Calhoun had a strong background in marketing writing but had to pick up the more technical aspects of writing and editing in his job. Dave Wright began his technical writing career with a strong writing background and now works as a senior software engineer and information developer.

The Marketing Writer Gets Technical

Harry: When I came to write for a technology company nearly 14 years ago, I had been working as a marketing writer for over 20 years, so I knew the pitfalls that marketing writers—perhaps writers in general—encounter: nonexistent source material, clients who kept adding more product information while exhorting the writer to keep it short, and bad direction from people who tend to dislike my conversational writing style. I soon found that writing for technology companies presents a unique set of writing challenges, and that writing and editing technical copy was not the same as working with marketing copy.

Whatever marketing writers are selling—training programs, software, hardware, or some mixture—their employers or clients generally recognize them for performing the valuable function of selling the products. This activity can be regarded with suspicion in technical environments, where coworkers and clients alike tend to regard marketing as “fluff” and want writers to stick to product descriptions with a minimum of sell. To make matters worse, clients often want the writing loaded down with technical specifications and other copy that is sleep-inducing to those less technically inclined. These factors make it difficult to write the short, punchy copy that is at the heart of good marketing writing.

In the years since I’ve increasingly written and edited more technical pieces, I have found that people who design the products often think these products stand on their own without having to address marketing issues. Writing from the viewpoint of an engineer or programmer, or editing their words, I just don’t get the marketing “oomph” so much as just the straight facts. I’ve found this to be an eye-opening, interesting, and in some ways refreshing approach. I don’t have to sell the product so much as let it stand up for itself.

So how do writers know when to write in a more technical style and when to use their marketing skills? Part of it, obviously, is what the client wants and what the written piece is intended to achieve. If the client wants a strictly informative piece, a white paper that sticks to the facts and relies on no marketing “wow factor,” that’s what the writer should shoot for. If the client wants to sell his or her product, then off to marketing land we go.

With my background in marketing, it’s easy to steer my client toward benefits-oriented writing. But as I’ve gotten into more technical writing and editing, I find that subject matter experts from development groups often want to explain how a product works, or how it was developed instead of how it will benefit the customer. And so I’ve had to learn to do this type of writing. It’s not that hard, really—just different and a change from what I’ve been doing for most of my career!

What You Need to Know

Harry: At companies such as IBM*, where various types of writing are performed, a marketing writer needs an unusual blend of writing skills to thrive. A rule of thumb is that if you’re doing marketing writing, a high-level knowledge of how the product works is all that’s really necessary. If you need to understand the product more intimately and describe it in detail, it’s probably not effective marketing so much as technical writing.

What you do need to be intimately familiar with are the benefits of the product to the target audience. Writing about IBM® Worklight® Version 6.1, for example, I only had to know the rudiments of the product and its strengths so that I could market them to an end user. When I had to switch my focus to technical writing, however, I needed to know the full range of Worklight Version 6.1 functions—not only those needed to market or sell the product. So while some writing, like marketing copy, strives to impart information that sells the product, technical writing involves communicating complex information to those who need it to accomplish some task or goal—including simply understanding the overall product better. According to the website techwhirl.com, “technical writing is sometimes defined as simplifying the complex.”

My marketing copy glossed over the deeper points of a product—who cared whether Worklight helped users to efficiently develop, deploy, run, and manage HTML5, hybrid and native mobile applications, or standards-based technologies and tools? All I cared about was that it helped Worklight users reduce their time to market, make development cheaper and less complex, and give them a better user experience. When I started writing technical documents, I had to care about, and pay attention to, all those finer points that made the product what it was—not just the benefits to the end user, but how and why it produced those benefits.

A Technical Writer with a Strong Writing Background

Dave: Before taking a corporate technical writing position about 20 years ago, I’d worked as a newspaper writer and photographer, published short fiction and scholarly pieces, completed graduate degrees with an emphasis in writing, and taught all of the standard university-level writing courses. Now when I see traditional coursework for Master’s degrees in technical communication, the assignments are familiar because I’ve taught those subjects. It’s said that if you want to really learn something, teach it, and I’ve found that to be true.

Although I was well-prepared to become a technical communication professional in terms of writing experience and skills, I still had much to learn, and the “applied science” aspect, grappling with and learning technical content and working in a highly technical environment, presents a constant learning curve. I believe that successful technical writers must know how to learn and how to use strategies for developing and delivering content as efficiently as possible. If Flaubert actually spent an entire day to change one word in a sentence, and then change it back … that wouldn’t do in a technical communication role.

Considering the challenges of writing in a technical company, people often focus first on the technical nature of the content. What’s a node? What’s an image volume? What’s a namespace? And how do these things work? While the jargon and the functions can be learned, doing so across a range of products can be a difficult technical endeavor. Distilling design and architectural specifications totaling in the hundreds of pages, and then developing from those the nuggets needed by end users, can be a daunting task.

The Technical Environment

Dave: Surrounding the technical content is the technical environment itself, the tools and processes and the progressive churn involved in delivering the product. Highly technical people often create complex technical processes. Anyone using DITA-XML with content reference tags for content re-use, and single sourcing files to support multiple products, where anything from single words to entire sections can be made to display or disappear depending on proper code management, is working in a complex environment. This type of setup can involve thousands of files, and the processes that produce the output from this setup are equally if not even more complex. Some people have the technical aptitude to manage it and others do not. The end deliverable can be a website containing thousands of files with thousands of links, or large, product-integrated software documentation. Technical communicators must ensure that each element works, that the text meets quality and accessibility standards, and that the content is accurate and up to date.

My first position as a technical writer involved working with one source file version control system, one defect tracking tool, and one content creation tool. A few companies and many years later, I now need to be handy with four file version control systems, three defect tracking tools, four content creation tools, and a slew of other software tools as required for related tasks—tools such as Perl, JavaScript, FTP software, Putty, Cygwin, Tidy, and Saxon. Translation processes involve even more tools, as files must be packaged and shipped to translation centers, processed in a variety of languages, and then likewise pass content verification and quality control checks.

While needing to stay current with those tools, writers in a large technological company must also navigate changing standards and requirements that help present a consistent product design, lessening customer learning curves and capitalizing on an established market brand. Information architecture also presents certain demands that must be met, again involving a set of standards and requirements. So, too, with project management, with eLearning, with graphical user interface design. The more of these elements that people cover in their work, the more complex and demanding their day-to-day activities. One significant reward in working within a large technical company is that these areas present growth and leadership opportunities. A company with a lot of seats to fill often finds that writers have the skills necessary to succeed in a wide variety of roles.

* The authors are speaking for themselves and not on behalf of IBM. The information presented here does not necessarily represent IBM’s positions, strategies, or opinions.

Harry Calhoun (1calhoun@us.ibm.com) is a content developer in IBM ITSO Global Content Services. His years of writing experience include work published in magazines such as Writer’s Digest and Mississippi Arts and Letters and an award-winning career in marketing. In his IBM career, he has won several STC awards and has worked on projects ranging from brochures to email campaigns and Flash presentations.

Dave Wright, PhD, is a senior software engineer and information developer in IBM’s Storage and Technology Group. He shares responsibility for product user information across multiple Storage products, and has had pieces in various publications including Northwest Review, American Literary Review, Quarterly West, and STC’s Intercom magazine.