Man versus machine | If John Henry was a technical writer

There's no use arguing against the notion that content management systems, automation scripts, and fancy tools can make a technical writer more efficient. Case study after case study drives that point home clearly. However, there will always be times when a fly-by-the-seat-of-your-pants approach, powered by sheer effort and rapid decision making, can win the day.

The question is knowing when to use such an approach.

Consider John Henry. The folk tale presents Henry as a steel driver who worked the railroad lines. His strength and pace were legendary; he could tunnel through rock and drive railroad spikes faster than anyone working the rails.

Like the modern technical writer, Henry came face to face with machines that were designed to make his job more efficient. (Or, in his case, irrelevant).

John Henry wouldn't bow to the machines. Convinced that he was faster, he challenged the new steam-powered drilling machine to a race - his mighty hammer against the machine's relentless pace. And, amazingly, he won.

But it killed him.

Technical writers face the same risk when they let pride, denial, or even fear lure them away from automation, content management, and other time-saving technologies.

So why is John Henry's manual approach so appealing?

Not all jobs are a good fit for automation. For example, implementing a content management system can be costly and labor intensive. Writing automation scripts may require assistance from programmers. And, a formalized documentation process can be overkill for small projects that don't fit neatly into a pre-planned workflow.

In some cases, you may be better off just sitting down in front of your keyboard and pounding out some documentation in whatever format feels the most natural.

Before you dive in, here are some guidelines that may help you in deciding whether to trust your established tools and processes, or your intuition and strength-of-will.

Size: How big is the project? Large scale projects, with many pages of documentation or many discrete topics, will benefit most from automation, content management, and a formalized process. The efficiency gains from tools and processes are increased by the sheer scale of the project. Small projects, on the other hand, might not be worth the setup time required for a formalized approach.

Consistency: Does the project involve many similar chunks of content? If so, repetitive tasks can be automated, saving you time. However, if you are working on many bits of content that are relatively different, you won't find much benefit from trying to automate repetitive tasks.

Collaboration: Are you working with a team? If so, a formalized approach will ensure that you are all producing content in a consistent manner and of consistent quality. Using the same tools and processes makes sense for collaborative documentation. However, if you are flying solo, you have less reason to worry about structure. Just be sure to take careful notes when flying by the seat of your pants, in case you have to re-visit the project at a later time.

Standardization: Does your output need to fit specific standards, or work in a specific environment? If so, you'll want to follow a process that ensures meeting those standards and use tools that generate standards-compliant output. If the output doesn't matter, you have more freedom to follow your customer-focused intuition.

Winging it isn't always a bad idea. Just be careful. Machines, automation, and technology can make you much more efficient in many situations.

Consider carefully whether a John Henry approach makes sense given the requirements of the project. If so, feel free to swing your mighty hammer with liberty, and win the day.

The tools are secondary to the message

A few weeks back I was introducing my 10-year old son to the art of computer programming. We were dabbling with an old version of BASIC, which he found both fun and fascinating; he could make games, draw graphics, and process input from the keyboard with just a few commands.

All was going well until my memory failed, and I couldn't remember the syntax for parsing string variables. (They say the memory is the first thing to go.) The help in the compiler / editor wasn't as thorough as I needed and the examples were too abstract to fit our code.

My son waited patiently while I stared blankly at the screen, hoping my synapses would reconnect. They didn't.

Fortunately, I own a heavy printed manual on the particular flavor of BASIC that we were using. I pulled it out and blew off the dust. I flipped to the index, found the section on string variables, and skimmed the chapter. Sure enough, it had detailed examples that clarified the situation. I wrote down the code we needed and my son typed it into the editor. He compiled the program and watched with excitement as it lit up the screen. Success!

What's interesting is that...

  • The answer to our particular question wasn't stored on a help server.
  • I didn't find it via a search engine.
  • It likely wasn't written in XML, or even SGML. (The book was printed in the early 80's).
  • Social media wasn't part of the development process.
  • No help authoring tool was involved in it's creation.
  • It didn't have a mobile CSS attached.

It was just words on paper.

It could have been written on rice paper and written with a quill pen. But it was the right words on paper. The words I needed.

Technology is amazing. In fact, I'm a strong believer in Buckminster Fuller's notions of ephemeralization. However, the flip side of ephemeralization is that as technology becomes more complex, human life should become more simple. As I sit in front of a computer each day writing code to make our publishing processes more efficient, a part of me (the Luddite part) keeps my ambition in check.

"Just words on paper," it says.

So, how does this apply to technical writing?

Just focus on picking the right words; let the technology take care of itself.