Search results

With All This Fuss About Tools, Three Best Practice Attitudes

by Tom Johnson on Aug 13, 2008
categories: technical-writing

A variety of tools

A few weeks ago I started experimenting with surveys in my sidebar, mostly informal, and mainly to try out different WordPress plugins. Little did I know my surveys would incite so much controversy.

The latest poll, "Which Authoring Tool Is Best for You?" has received nearly 600 votes from people around the world, and was discussed at length on the HATT listserv. In all this discussion, I've realized one thing: technical writers are passionate about the tools they use.

"Passionate" is probably too positive a term. More like fanatical or zealous – but really technical writers span the spectrum with attitudes here. Some are fanatical, others are heavily invested, a few are open-minded, others are confused, and some are downright nasty.

The war over tools isn't unique to the field of tech comm. It's human nature to cling to a brand and promote it as the best. Think Dodge versus Ford trucks, Harley versus Yamaha motorcycles, BYU versus the University of Utah (replace with your local college rivalries), the Yankees versus the Red Sox, Mac versus PC, iPhone versus BlackBerry, West Coast versus East Coast, Twitter versus Plurk. The war of brands is pervasive and probably dates back to cavemen promoting different types of clubs to maim their kill.

Even as I write this post, someone has just twittered, "Movable Type, the most powerful blog software out there, hit 4.2 today." Is Movable Type really the most powerful? Or is it WordPress, or some other?

Replace the word "software" with any other product and you catch the spirit of the branding war. Ford, the most powerful truck out there. iPhone, the most powerful mobile device. The Yankees, the most powerful baseball team to ever ….

An Alternative Point of View

Although tools seem to play a significant role in technical authoring, some people disagree. Bill Swallow is "shaking [his] head at all the tools survey nonsense going on lately." He feels tools should play a minimal role in any project, not foregrounding the more important aspects of content generation. Spending 20% of your time formatting, structuring, designing and styling your content with a tool is "a huge waste of time," he says.

Instead, tools should play "a very little role in our day to day work (or should)." Writers should simply choose the right tool for the job -- like a skilled mechanic selecting a wrench from a toolbox -- and go to work writing instead of wrestling with the tool.

Perhaps if everyone could work like this, we wouldn't so easily slip into Pharisee-Saducee-like tool discussions. But while this scenario is ideal, it's hard to implement because not everyone has the technical prowess of a Bill Swallow to make a tool eat out of your hand. In setting up single sourcing scenarios, or structured authoring templates, the tools and process can be a monster you battle. (Of course, once you set everything up, it's no longer such a monster.)

Best Practice Attitudes

My discussion about tools isn't conclusive nor is it meant to be. So instead I give you three "best practice attitudes" to have towards tools.

1. Embrace Tool Learning

You're a technical writer, right? This is what you do – learn confusing software applications that engineers create. Learning tools should be your strength, not your weakness.

To make life easier, try not to learn a tool all at once. It's better to take small bites over a series of weeks rather than pull an all-nighter under pressure.

2. Recognize that the "Best Tool" Is Relative

Certain tools are right for certain situations, skillsets, and corporate contexts. What's right for you may not be right for another.

For example, WordPress may be tremendously powerful, but many users can't understand it, so Blogger might be more appropriate, even though it's less powerful. Similarly, DITA may be the way to go if you have heavy reuse, but if you only have one manual and no reuse, it would be overkill. Camtasia is great if you're creating screencast tutorials, but Captivate excels at interactivity. Framemaker is better at long documents, but Word is fine if the job's shorter. Right is relative.

3. Expose Knowledge Gaps

The next time a "best tool" war flares up, ask each person if they've used the other tool, and if so, to what extent. When we admit the limits of our knowledge, we're more apt to be humble and open-minded when it comes to tool comparisons.


In this post, I have not taken a position of tool agnosticism. I do think that some tools are better for certain jobs than others. But we can be a lot more level-headed and open-minded when it comes to discussions about tools.


photo from Flickr

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.