The Writer's Comfort Zone

Over the last week, I’ve had several conversations about the challenges involved in producing technical communications, aka tech writing. First, there was a great conversation as part of an “Ask Me Anything” session for The Writer’s Comfort Zone, where one of the participants described her struggle to write about a subject she felt passionately about but was overwhelmed by. Then there was an interesting question posed by TechWriterGirl on Instagram about whether there was such a thing as a well-documented API. (I said no to that one as I’ve worked with experienced developer teams for years; they all struggle with documentation.)

What makes tech writing so hard?

• Knowing enough to write about the subject
• Managing the team
• Consistency of style
• Avoiding jargon
• Balancing engagement with precision (tone)
• Forgetting the outline (need to support a logical flow)

What Do Tech Writers Write?

Tech writing has its own specialties, not dissimilar from other writing disciplines. For example, poets might specialize in haiku, iambic pentameter, or limericks. Fiction writers may gravitate toward short stories, novels, or plays. Marketing sees people focused on copywriting, product descriptions, and blogging. And, of course, any one type of writer might explore any style and genre, so consider this list a loose analogy.

Tech writers often specialize in white papers, software manuals, code documentation, and geeky blogs. And like all other writers, they have hurdles to overcome.

Common Tech Writing Challenges

Subject Matter Expertise

The fortunate tech writer has a tight area of subject matter expertise. More often, however, tech writers are generalists who are expected to write on various topics where they are not, personally, the subject matter expert. If ever there was a recipe for imposter syndrome, this would be it! Tech writers have to get comfortable writing about subjects where they might not have operational or hands-on experience. Instead, they have to rely on research or those individuals who have that experience, leading to the next challenge, team management.

Team Management

While some tech writers are freelancers working in their own consulting businesses, many work as part of a team. Some software companies have entire departments of tech writers that work with each other and assign subject matter experts to document whatever needs documenting. 

Unfortunately, it is never as simple as saying, “Hey, Pat! Tell me about the new system architecture so I can capture all the relevant guidance for the world.” For one thing, Pat probably has more immediate demands on their time. For another, Pat is probably just one of the people the writer must consult, and others might disagree with what the writer is supposed to capture. 

The tech writer needs decent team management skills, even when they aren’t the team leader. Otherwise, they might find themselves at the tail end of the priorities and at a loss for what to write.

Consistency of Style

As if having to become just expert enough to do the topic justice and wrangle teams to make sure the writing gets done, the tech writer will also have to deal with the issue of style. Particularly in a team writing scenario, a document may read like twelve people were doing a tech writing improv. This random (as far as the reader is concerned) variation in how the text is written is a huge problem. It disrupts the reader’s ability to comprehend the text. 

One could argue that this isn’t a writer problem; it’s an editor problem. And that’s not wrong, per se. However, the line between “writer” and “editor” is very, very blurry. I personally don’t think one can be a good tech writer without decent editing skills. I also don’t think one can be an editor without decent writing skills. This might be a good question for my writers community.

Avoiding Jargon

And since we’ve covered the challenge of writing style, it’s time to admit that getting caught up in the jargon is a problem, too. The tech industry abounds with acronyms, abbreviations, and portmanteaus. Even worse, it is full of ordinary words with particular meanings in a given industry. 

Small teams can get away with using jargon as they all (probably) know what they intend with the text. As soon as a document goes out to a broader audience, however, that jargon that was so prevalent in team discussions is going to be a barrier to others’ understanding of the text.

Precision versus Engagement

Tech writing must be precise. It must be accurate; it must be unambiguous; it must be … boring? Tech writers are often tightly constrained when it comes to word choice and phrasing. And yet, especially for white papers and blogs, the text must be engaging enough to keep the audience interested. The balance between precision and engagement changes with every topic and every audience.

Logical Flow and Outlines

Tech readers, perhaps more than any other audience, demand a logical flow to the content. The tech writer’s challenge, then, is to create an outline that supports that logical flow. That’s not as easy as it sounds; it is hard to write an outline when the writer is less familiar with the content.

Having an outline has several nice side effects. For one thing, it helps assign sections of the work to others. They can see where their work will fit, and the writer can see where to plug it in when it comes back. For another, it allows the writer to measure their writing pace (a useful thing when writing to a deadline).

Still, creating this outline is often more time-consuming than anyone expects, so as far as challenges go, it’s a big one.

Wrap up

Tech writers have a tough job. Those that can overcome the challenges are worth their weight in iridium. If you’re interested in engaging in this field, I highly recommend you start reading whatever articles and papers you can find in the area of tech most interesting to you. Whether that is tech journalism, Internet standards, or software documentation, read as much as possible. You’ll get a better sense of what works, what doesn’t, and how it needs to be organized.

Good luck!

If you know of others that might enjoy being part of a community designed to support writers, please send them here to The Writer’s Comfort Zone!