Examining the World of the Technical Writer - dummies

Examining the World of the Technical Writer

By Sheryl Lindsell-Roberts

People who write technical documents come from all walks of life — and most aren’t technical writers per se. Here are some actual situations of people who were called upon to write technical documents in the course of their professions:

  • Computer programmer: Pat graduated with a degree in computer science and was hired as a software developer for a company in the fast track. Several months later, the company felt a financial pinch and laid off the technical writers. Pat had a big deliverable due in a few months, and her supervisor told her that she had to write a user manual. Sophomore English (which Pat struggled through and loathed) didn’t prepare her for this type of assignment. After all, Shakespeare wasn’t a technical sort of guy. Poor Pat had to muddle through writing the user manual and got gray hair prematurely.
  • Manufacturing specialist: Bill worked for a manufacturing company for many years and developed a piece of equipment that was expected to revolutionize the industry. The equipment made its debut in Germany at the industry’s largest conference. Bill’s supervisor asked him to deliver a paper (the industry term for a making technical presentation) at the conference. The audience would consist of more than 200 top industry professionals. Not only did Bill fear the podium more than the dentist’s drill, he didn’t know to prepare or deliver a technical paper — especially in a foreign country for an audience of this caliber.
  • Mad scientist: While working at a pharmaceutical company, Nathaniel had a major breakthrough on a treatment that promised to prevent baldness. The company president asked him to write an article for a major medical journal. Although Nathaniel was flattered by the president’s request, he didn’t know the first thing about writing or submitting a technical article.
  • Sales representative: Lynette was a sales representative for a worldwide computer distributor. She’d often be away from home for weeks at a time. After 15 years as a road warrior, Lynette suffered from burnout. (She used to leave her picture on the fireplace mantle so that her family wouldn’t forget her.) Lynette had been reading about the burgeoning field of tech writing. She called a local college, got all the literature, and decided to pursue a master’s degree in technical writing.

Although the names have been changed to protect the innocent (Lynette, for example, hasn’t turned in her resignation yet), scenarios such as these are typical. Technical people who aren’t trained writers are constantly asked to write technical documents. Their education and work experience rarely prepare them for this type of challenge.

Documents of the technical kind

People in specialized fields write documents that relate to technical or complex subjects. Unlike business documents that are generally written by one person, technical documents are often a collaborative effort between a writer, subject matter expert (SME), editor, and others. Technical documents are generally intended for lots of readers. Here are some commonly written technical documents — paper and electronic:

  • Abstracts
  • Articles for publication
  • Computer-based training (CBT)
  • Evaluation forms
  • Executive summaries
  • Functional and detail specifications
  • Online help
  • Presentations
  • Questionnaires
  • Reports
  • Training material (paper or electronic)
  • User manuals
  • Web-based training (WBT)

Assigning responsibility for technical documents

The responsibility for writing technical documents depends on a company’s structure and resources. Here are three ways that companies typically generate technical documents:

1. Technical gurus (engineers, software developers, and others) write their own documents. Some of these people may have taken writing courses, but most have no training in writing a cohesive document. These “technical writers” often overlook steps to share with their readers because these steps are obvious to them. And they probably haven’t identified the needs of their readers. They write what’s important to them.

2. These same gurus may draft documents and then turn the drafts over to technical writers to edit, format, and polish. Unless the technical writer has an opportunity to learn the subject matter intimately, many of the steps that may have been overlooked by the guru aren’t identified by the writer or editor. This process does, however, produce a document that may be more pleasing to the eye — for what that’s worth.

3. A technical writer is called in from the onset of a project. The writer works with the developer who’s the subject matter expert (SME). They work as a collaborative team, each adding their expertise to the project. This approach is generally the best of all possible worlds.

Strategy, not software

Anyone who writes technical documents must understand how critical it is to take a strategic approach. For example, if you design a custom home, do you first call someone to wield a hammer? Of course not. A hammer is merely a tool. To design a custom home, you call an architect — a trained professional who designs layout; renders plans for the plumbing, electrical, and heating systems; and provides the structure. Then you call someone who knows hammers.

The same holds true in technical writing. Effective technical documents require an information architect — a technical writer. Whether this person is a professional technical writer or an engineer or software developer who writes technical documents, she must plan, design, and provide logical structure. Anyone can learn to use the software to create the document. Much like the hammer, software is merely a tool. The key to writing a great document is strategy, not software.

Very few people have that broad a knowledge base. Technical writing is about using strategy and resources to write clear, accurate, and logical documents. If you apply a logical strategy and avail yourself of resources, you can write just about anything — from turning on your computer to assembling a jet airplane.

What you need to succeed

Here is a snapshot of what it takes to write clear and understandable technical documents:

  • Show respect for your reader. You must always write with respect for your reader. Write with a positive attitude, not with arrogance. Technical writers often speak of their readers arrogantly with remarks such as, “We don’t write these documents for idiots. If they’re that stupid, they shouldn’t be using this product.” (Well, excuuuuse me!) Even the brightest humanoid may experience confusion when presented with something entirely new.
  • Pay keen attention to details. You show your keen eye for detail in the way you think about what you write. Here are a few bulleted items extracted from a resume from someone who was applying for a position as a technical writer:

• “Contributing writer to weekly city newspaper.” (Which newspaper? What does he write about? The newspaper is weekly, but is his contribution weekly? Bimonthly? Monthly?)

• “Generated technical reports.” (What does he mean by “generated”? Did he write the report or merely click the Print button and spew them out?)

• This writer wasn’t able to identify the details that a potential employer wants answered. Therefore, it was obvious that he couldn’t identify the details that his audience needs. You must be able to anticipate the questions your readers will ask, and you must answer them.

  • Know your readers and their requirements. Unlike a letter that you may write for a specific reader, you often write a technical document for a diverse group of readers. You must understand their needs in order to determine how you write the document and whether print or electronic media is appropriate.
  • Collaborative efforts. To tweak John Donne’s famous quote: No tech writer is an island. Even if you’re the only tech writer on your project, you’ll work with people inside or outside the organization: SMEs, editors, publication/electronic specialists, and end users.
  • Demonstrate the ability to leg-o your ego. Last but not least, you must be able to leave your ego at the door. Your finished document will often be very different from your original draft. Everyone who reviews the document feels compelled to pick up a pen and mark it up. It’s all part of the process — the need to make a contribution. So, be prepared to have your work edited, re-edited, and perhaps ripped to shreds.