Tech writers: The bard class of the corporate world

In D&D and related role-playing games (Dungeons and Dragons, and yes, I’m going full geek), the Bard character class gains a ton of skills: They’re a bit fighter, a bit thief (or rogue, if you prefer), and also have a bit of magical ability.

The point is: They’re flexible. They’ll never hit as hard as a fighter, aren’t as sneaky as a thief, and won’t cast as many spells as a wizard. But because they don’t specialize, they’re useful in many situations, and they’re often an asset to adventuring parties.

Lots of skills, very versatile, an asset to their team…just like technical writers!

Ok, I sense your doubt. Let me explain.


Last week, I started writing a post that described my typical work day. I wrote 600 words before it became overloaded with conditional statements. Then Mark Baker explained why my description was floundering, and that column was really dead.

Instead of describing a mythical day, I’ll focus on the sorts of jobs that I’ve done, all while having the job title of Technical Writer (Junior, Senior, Principal, Lead, and Manager). I’ll try to catalog the skills that I’ve picked up as a technical writer, which (spoilers!) includes more than writing.

The Basics

If you’re a tech writer, you know the basics: content creator (specialist or generalist), proofreader, content editor. Most writers will also be product testers, graphic designers (at least a little), and CMS experts. The majority of technical writers can’t focus on a two or three skills during their careers. Even if you focus on writing content, error messages, installation guides, online help, and admin guides are very different beasts. And an API reference is unlike any of those.

I became a tech writer because I could write (English/Rhetoric/History in college) and I knew how to use computers. And not just “use Word:” After an unhelpful university sysadmin created an account for me and then went back to playing xtrek, it was up to me to figure out Unix well enough to send email, create a .plan (all the uncool kids had them), chmod the config files so they couldn’t be hacked (easily), and even face the usability horrors of vi (no doubt developed by programmers who took “inscrutable” and “arbitrary” as compliments).

And I spent more hours fighting with config.sys settings than I did actually playing Wolfenstein, once I finally got it to run.

Basically: I had enough knowledge to convince someone that I knew enough to be useful.

(As an aside, if you hear anyone talking about the “good old days” of early x86 computers, just say two words: IRQ conflicts. If they don’t turn pale, they weren’t there.)

Getting back to the point

So most tech writers need to cover the basics of creating and editing content, and then handling at least part of the publishing process. Obviously, being technically oriented doesn’t hurt. Since I knew about computers, I was also tasked with handling a couple of test machines that we had, and helping people use some nifty new external hard drives.

Yes, “Did you try turning it off and on again?” was something that I said. In fact, “Did you try turning it ON?” solved most of the problems.

When I moved to a startup after my first job at a relatively large company, I learned how to deal with the management tasks that my manager didn’t have time for (plan realistic doc schedules) and handle the publishing process (creating finished PDFs and checking in the online help). I broke the product build once through some mistake with the check-in system, and that’s one hell of a learning experience.

HTML and other skills

Write a bunch of online help and you’ll need to learn HTML. Maybe it was just the problematic early online help tools, but I often found it easier to fix things in HTML than to try to figure out why a bullet list was suddenly nesting inside itself, or why a table was pushing far beyond the page margins.

From there, I went to another startup that didn’t have anything in the way of established documentation. I learned how to build FrameMaker templates, work closely with product managers to create and deliver entire doc sets (a few manuals and two online help systems), create code samples, and just generally be responsible for everything a doc team needs to do.

I also had to learn how to schedule my time in the most aggressive way possible: Don’t waste time chasing down minor details, just learn to ask for help! Yes, I should have learned that earlier, but I had the buffer of a large doc team, or a least a manager who could head me off and point me in the right direction.

Internal communication skills

A tech writer must learn how to communicate effectively and unambiguously…with people in their own company. Obviously, we need to focus on this in our documentation, but I needed to learn that even within my own company (or even own department) that not everyone understands things the same way that I do. Why is a meeting about this or that feature important? To a programmer, it’s going to sound like the lowest on a long list of priorities, especially if they’re near a code freeze date.

So tech writers need to be good at organizing and running very efficient meetings, or else their SMEs won’t show up at all.

Moving away from PDF

Eventually, I was no longer delivering documents in PDF format. I took a job with a company that delivered documentation via a wiki (hey, I’d used Wikipedia, so I was totally qualified!). I had to learn how to deliver online-only documentation, and that meant reading about information architecture, web-focused writing, and content strategy.

Why content strategy?

Even though I wasn’t responsible for the company’s entire online communication, the documentation I wrote addressed the needs of very different customers. I needed an overall plan.

A great idea from content strategy is the idea of the curator role. I was writing a lot of help topics, and although I was doing a reasonable job of organizing them (the information architecture part), it certainly wasn’t perfect. With topics spanning half a dozen or so areas (manuals, basically), and each with its own sub-area, I needed a better way of tracking what was there.

I started a doc audit. It not only helped me figure out what I had, but also what state it was in. I evaluated every topic for a few factors, including its relevance, age, and usefulness. This allowed me to find weak topics, old topics, missing topics, and topics that could be combined.

I don’t claim to be a real, corporate-wide content strategist, but I do know enough to build a strategy for my own content.

What about DITA?

Ugh. I’m not a fan of DITA. I know it’s great when you’re writing huge docs that reuse a lot of content, but I don’t do that. I find it too constraining, with too much overhead, and I just don’t want to deal with it. I’m not writing content that needs to be reused multiple times, so the cost of setting up a DITA system is greater than any benefit I would gain.

I’ve also seen it done really badly, and I’ve had to sort through and rebuild decent manuals out of topics that had been horribly DITA-ized. (One manual had three chapters: Concept, Procedure, and Reference. It was, technically, in DITA structure, but it was completely unusable.)

On the other hand, I have written a lot of structured documentation, and I’m no stranger to XML. I don’t like the limitations and forced constraints of DITA, but I could work with it. If I had to.

DITA experience is another skill that’s worth having. And understanding how to write structured docs will serve you well.

Answering user questions in other ways

Training is a whole other field, but there’s a lot of overlap. The main difference is that a student isn’t going to sit in a training room (or watch an online course) and read for 8 hours at a time. But a tech writer can help by creating training handouts (I’m doing that in my current job), and helping to develop training content (information used to build training presentations and exercises).

Customer support is another role that a tech writer can help with; to be honest, though, it probably won’t pay as much. And you have to deal with irate customers. But you can pitch in when necessary and help your users. Plus, as I’ve said before, it’s a great way to learn what your customers are beating their heads against when using your product. Sitting in a customer support role for a week is pretty darn illuminating. If your tech writing team is far removed from customer support, then I recommend going out of your way to get to know them.

How much of this is necessary?

How much is necessary? That depends on what you want to do. It’s certainly possible to get by without some, or even many, of these skills. Many tech writers won’t touch wikis during their careers, and few will ever have to deal directly with user issues. Many more writers work with DITA every day, and although that sounds like cruel punishment to me, they obviously have a very different opinion (and wonder how I can create decent docs without it).

A lot of it comes down to curiosity, interest in the subject, and a willingness to learn. I’ve turned away candidates who worked with online help for years but never bothered to learn HTML. But I was hiring for roles where the writer had to be self-sufficient, and I wouldn’t be able to help fix every little problem. Showing a willingness to learn new skills will make your managers, or prospective managers, happy. (Conversely, saying “I don’t like to talk to programmers” will end your interview early.)

New areas of learning

My next challenge is to learn about the concepts and practice of customer success. This is another field that’s at least adjacent to technical writing: The goal is to make sure that your customers are getting full value from your product, to understand what will make them successful, and to make sure that they’re using your product to make that happen. This is what tech writers should strive for, but tech writers have to encompass all customers, and not just one at a time. So the product documentation is diluted of necessity as it tries to address the needs of the majority of customers. Customer success needs to narrow that focus, to pull it in and direct it towards individual customers. That’s just a starting point, and a path that I’m using to enter a new role.

Unfortunately, “improve the documentation” is not the one thing that will make customers love your product. Improving the publishing process or document format will help the doc team, but customers don’t care about that. Gaining a more complete understanding of your customer needs will help you shape your user docs into something that better addresses those needs.

The big skill

All of that relies on the overarching soft skill of communication, the thing that all tech writers need to develop well (and quickly). I’m often a center of communication in a company, crossing multiple departments to pull together product strategy, customer requirements, and feature descriptions. Without pulling together information from multiple groups, you can’t plan a doc set, prioritize what needs to be written, and write the specific content. No magic conveyor belt will deliver that info directly to your desk.

I’ve made that mistake: “The engineers will get back to me when they’ve made a change.” No, they won’t. Because once they make that change, they have 50 more tasks to complete by the end of the week. I guess under communication comes the skill “gathering information without being an annoying pest.” I wish I could give good advice about that one. Some writers recommend baking cookies; coming from me, that would be closer to a threat. Respect your SMEs, do your best not to bother them when they’re swamped, and learn what they respond to (I’ve worked with some who prefer that I set up time on their calendars, and others who ignored meeting requests from anyone below a VP).

Bricks and mortar

Remember that this is from the perspective of someone who is an “I can do that!” sort of writer, not “I’m the absolute best at .” I am, to use Mark Baker’s description, a very mortar-y type of technical writer (and information architect, content strategist, and n00b customer success manager). That’s what I enjoy, and find fulfillment in. But there’s certainly a call for more brick-y tech writer roles: API-only writers, DITA masters, etc.

My days are very fluid, and I can rarely predict what I’ll be working on with much certainty. I’ll know that I need to write specific topics, but it’s also likely that I’ll be pulled into a transition meeting, need to deal with doc changes based on a customer support ticket (and in my current role, also handle that support ticket), test some new features (and take screenshots and write descriptions of bugs that I find), and fit in some meetings with SMEs when they have time.

Concluding this tale

In short: Embrace your inner bard! Pick up any and all career skills that interest you and help your adventuring party…er…your department. You’ll probably need a CMS expert, a publishing genius, someone who can create awe-inspiring graphics, a CSS master, and an editor extraordinaire. Unless you have a very large team, these skills will have to overlap.

And if you’re a one-person tech writing team, like many writers in small companies or small writing departments these days, then you truly are your company’s bard.

But please don’t ask me to sing. It’s not pretty.


2 thoughts on “Tech writers: The bard class of the corporate world

Comments are closed.