Search results

14 Widespread Myths about Technical Writing

by Tom Johnson on Jun 26, 2008
categories: technical-writing

Jefferson McClure added a thought-provoking article link on WriterRiver.com titled "Myths of Technical Writing." The article is by Bob Doyle and appears on the dita.xml.org wiki site here. In the article, Doyle and other wiki contributors mention 4 myths about technical writing:

  1. The GlueText Myth
  2. The Stem Sentences Myth
  3. The Front-Matter Page-Numbering Myth
  4. The Callouts on Graphics Myth

You'll have to read the original for the details. The debunking of these myths is supposed to help you embrace a structured authoring methodology like DITA. The myths are genuinely insightful, and it got me thinking about myths in a larger sense.

In part, I'm reflecting on myths because I was recently invited to speak to students at a professional writing conference at BYU Idaho in the fall with the topic, "Three Myths About Technical Writers."

Apparently, many students pursing English degrees assume technical writers have "sold out." They think technical writing is a "fallback" career. It's something you can do if you're starving and don't have any other options. Oh, the financial naivete and idealism ...

I'm not sure what will convince people immersed in Charles Dickens and Edgar Allen Poe and Chaucer and Emily Dickinson, who are writing about deconstructionism and feminism and the intersection of Shakespearian influences on postmodern authors, etc., that technical writing is more than just "press this button here to program your VCR..."

It will be a challenge, but one worth taking. When I was a student at BYU, I held these same biases against technical writing. I acquired the myths from one presentation by a teacher who represented the English faculty on technical writing. In a nutshell, compared to the other English professors, she was the most boring of any I've ever met -- by a long shot. She talked about formatting phone books. I whispered a silent vow to myself that I would never, never become like her.  While she spoke of layout and design for banal texts, other professors ignited us with literary ideas.

I now have a personal vow to make technical writing look like one of the most appealing careers one could possibly pursue.

In addition to myths about technical writing as a sellout and fallback career, I can think of at least 10 other commonly held myths surrounding the field of technical communication. I offer them below.

1. Technical writers spend most of their time writing.

Totally untrue. Most tech writers spend about 10% of their time writing. The rest of their time they spend learning applications, noting bugs, providing usability feedback, structuring their content, setting up styles for their help files, troubleshooting their tools, strategizing help deliverables, training new users, formatting and laying out their content, updating existing content, meeting with project team members, and occasionally playing ping pong.

2. You can't get a job in technical writing unless you have technical writing samples; but you won't have samples until you have a job in technical writing.

Don't believe this for an instant. You're surrounded by technology -- your iPod, computer, DVD player, microwave, cell phone, BlackBerry, and everything else. Download a trial version of some help authoring tool, or even just open up Microsoft Word. Write instructions for something. Find an open source application with poor instructions and rewrite them. You don't have to create an entire user manual. Just give your potential employer some evidence of your capability.

3. A technical writer who has years of experience is more knowledgeable than one with fewer years of experience.

This myth is turning into my pet peeve. How many bios have you seen that begin, "Joe has 15 years of experience ..." or "Kate has over 20 years of experience as a technical writer...." Experience means nothing unless learning is taking place. I can go to my same job for 15 years, do the exact same tasks, use the exact same tools, never taking any creative risks or moving into new territory, just doing what I'm told, or what I've read, for my entire life. The pace of learning can be compressed into a very short time period, or it can drawn out over a life time. The time (years of experience) does not matter as much as the learning that takes place. (See this related post, MySQL CEO Says, "It is dangerous to hire someone with too much experience.")

4. The tools you know are more important than your industry knowledge.

Many job ads say you have to know RoboHelp, Photoshop, CSS, HTML, Javascript, C Sharp, InDesign, Dreamweaver, DITA, XML, XHTML, and so on. But really, if you have strong domain knowledge about an industry, that knowledge can be a lot more powerful than a specific tool. For example, if you work in the financial industry, a Series 7 license (which allows you to communicate with investors) is a lot more important than RoboHelp. It can take months of study to get your Series 7, and only a few weeks to pick up a tool. (See this related post, Doug Davis on the Job Side of Technical Writing -- Location, Industry Experience, and Salary.")

5. Be careful about having a blog, because all employers google you and will find it.

When I hear this, I cringe. The discussion always comes up among non-bloggers who think blogs are a wart you need to hide. Sure if you have an embarrassing MySpace page where you mix profanity with vulgarity and other shady content, that's a site you need to obliterate. But a professional blog demonstrating your knowledge of technical communication can be a powerful tool for getting an edge on other job candidates. It can also serve as a tool for professional development and keep you enthusiastic about your career.

6. Technical writing academics are disconnected with the profession and only have a tenuous idea about the actual practice of technical writing.

Many academics started out as technical writers and worked for years doing the same things we did. Are we practitioners so vain that we think the industry is rapidly changing from year to year, so much so that intelligent people who spend years immersed in texts, studies, journals, and experiments have no idea what our jobs involve? Academics may not be totally fluent with the latest tools, but that doesn't mean they're disconnected with technical writing practices and challenges. (See this related post, "Reflections on Allison Reynold's Talk on Job Skills for the Workplace.")

7. You can't have voice or style in technical writing. It has to be objective. And the fewer contractions, the better.

All writing has voice. You don't have to remove all sense of humanity from your writing. A writer who uses contractions, moves toward conversational style, and truly has voice will provide a better experience for the frustrated user who seeks human help rather than cold robotic formalese. The talk that changed me forever was this keynote by Kathy Sierra at SXSW, where she explains the need for human qualities in help material when users, in desperate frustration, finally click the help button. If you want to sound like a robot, eliminate all contractions from your writing. What tone do you think users respond better to?

8. Technical writers aren't allowed to contact users directly. They should get their information through the product manager, customer support, and marketing.

Here we see yet another wrong idea that will only put up roadblocks for worthwhile help. Joe Sokohl clarified this principle at Doc Train West 2008, calling it the Kobayashi Maru principle (a reference from Star Trek). He says you have to throw aside the idea that you can't contact users. Without this contact and the information you can gather from users, you're hopelessly doomed to write instructional material they don't want.

9. You can single source your material into all the formats your audience needs, if you just learn the right tool or technology.

When you learn to structure your content with DITA, you can magically transform all your content into every format your users need. NOT. The type of instructions you write for a one page quick reference guide varies from the kind of style you need for an iPhone or for a long manual. While I agree that you can single source online help to a software manual, the idea gets taken too far. (See this related post by Gordon McLean, "DITA Is Not the Answer.")

10. You have to be quite tech-savvy to be a good technical writer.

Actually, when you become so tech savvy that you can't imagine users not understanding how to disable a popup blocker or not knowing how to do a simple task, when you are stunned at users who double-click when they should single-click, or who single-click when they should double-click, at this point, you lose some ability to write for the lowest common denominator. It's not such a bad thing if you're technically challenged. So are most of your users! You'll be on a level playing field and will probably write a help manual that actually speaks their language. (See this related post, "The Curse of Knowledge -- The More You Know, the Worse You Become at Communicating that Knowledge.")

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.