Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

Stitcher radio

Search results

Upcoming event:
I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today.

Reader question: Is it a red flag in the hiring process if they tell you that you'll be the only tech writer, with complete control over everything?

by Tom Johnson on May 15, 2019 • 0 Comments
categories: general

A reader wonders whether having complete control as the lone writer in a company is a red flag he should watch out for, based on his previous experience. I agree that it is.

Hi Tom,

I’m writing to ask whether it’s a red flag that a hiring manager tells you that you’ll be the only tech writer in the group. A few years ago I found myself in a similar position. I was told I’d have complete control and autonomy with docs from end to end. Well, it soon became apparent that the group underestimated the amount of work required, and they seemingly had me editing and writing every written material in the company, from tech docs to marketing to reports and other content. It was overwhelming. Also, it seems my manager was mostly interested in making the docs look better visually. I was also trying to set up a docs-as-code workflow, but the position fizzled before I finished. Now as I look for another position, I just heard a similar promise from a hiring manager about being the only tech writer in the group. Is this a red flag I should watch out for?

Interesting question. To narrow the issue down a bit, the question is this: how do you know whether a company, which doesn’t have any other tech writers, is appropriately staffing the right number of tech writing resources for the work required?

This reminds me of a discussion I had with our localization team the other week. I asked if they feel like they have more work than two people can feasibly do. They laughed, as this was obviously a point of frequent discussion. They said there should be 3-4 people staffed to do the amount of work we have. I was kind of shocked, because I don’t know much about localization management and language QA. I was too embarrassed to say it, but I kind of thought one person might be enough.

From this experience and others, I’m guessing there’s a general principle at work here: most people underestimate the work involved in roles they do not understand. If you’re going into a company that doesn’t understand the technical writer role, expect that those managing you will underestimate the level of effort required to produce the results they want.

However, this is not to say that you should avoid these positions. You might have a lot of fun being king of the castle. You can make all the decisions about your tools, style guide, review process, and other workflows. In fact, I’m one of two technical writers in my current group. We write tech docs for the Amazon Appstore and its many products, service, and APIs that developers use to build and submit apps. I often feel like our team should be at least double if not triple the size. (We are, in fact, hiring, though.)

Overall, how do you persuade others, especially business managers with other specializations, that more technical writers are needed to achieve the kind of quality we expect and need? If I knew the answer to this question, I would have a much larger team. In fact, my posts about becoming a 10X tech writer and my explorations about productivity are related to this. So you’re basically asking the wrong person, but you’re also asking the right person because I’m equally interested in the question.

One answer might be to take shortcuts with tools. In my experience, most companies underestimate the work required to set up authoring and publishing tools for tech docs. I think most assume that tech writers just buy a tool that has everything already set up, because these same managers typically use Microsoft Word to achieve their writing needs. With Microsoft Word, you just install it and can be productive from the start. You certainly don’t need to create your own version of Microsoft Word, right?

And yet, if you’re implementing a docs-as-code workflow, you’re probably building out your own site, developing styles, includes, templates, and other features. You’re playing the role of a UX designer and developer in one. This is crazy, because you will not get much credit for it, in the same way that I don’t give higher-level managers credit for custom Word macros or hacks they might have done in their versions of Microsoft Word.

So I would recommend that you take a shortcut with tools and use pre-built solutions where possible. For example, maybe use Readme.io, Cloudcannon, Netlify CMS, or some of the tools provided by my sponsors — Document360, MadCap Flare, Paligo, or Stoplight. Consider using frameworks such as Bootstrap. Or see if you can hire out the initial design of the site. You could even just get a cloud version of Confluence.

If you can focus your energy on content rather than tools, you’ll probably be in better shape to tackle the other higher priority content needs. However, you also noted that your manager was mostly interested in the appearance of professional-looking docs. It’s not a given, just because you maybe bought a commercial tool, that the output will look professional. You’ll likely need to do a lot of custom stylesheet development or other branding. So you’ll unavoidably need to spend some time with tools one way or another. But trust me on this: Developing your own docs-as-code tooling from scratch can be a huge time sink for which you will get little or no credit (except from other tech writers). You realize the ROI over time.

Let’s suppose you’re using a pre-built solution, and this isn’t the time sink. You really need at least two people to do your job well. But your manager doesn’t understand this because he or she comes from another background and doesn’t understand tech docs. You’re the lone writer at the company, and they have no idea if you’re just sitting there playing Candy Crush with nothing to do, or if you’re just inefficient, because they don’t have other tech writers to compare you to, nor do they have a history of working with tech writers.

One solution might be to find out how many tech writers your competitors have, or other similar companies. Sometimes it’s hard to come by this information, as people are frequently reluctant to provide it. (For example, I’ve always wondered how many writers work on Google’s Appstore and Android sites and their related tech docs). And even if you were to acquire this data, I’m not sure exactly how you present it persuasively because so many other factors might account for different ratios.

I really have no idea what the answer to this question is. It probably ties in with the value propositions that tech writers have been trying to make for years. One idea I’ve been kicking around is maybe starting an internal blog, in part so others can have a deeper understanding of what tech writers do and think about. (But also because it seems like a lot of fun.) I also log tickets for pretty much everything I do, and try to keep others aware of doc updates through occasional email blasts.

But if you’re a lone tech writer, others will still not know how to gauge whether the 100 pages of documentation you wrote in a week, or the doc theme you coded from scratch, or the vector graphics you designed in excruciating detail, or the style guide decisions you made after hours of research is all just par for the course for a technical writer. So yeah, this is a red flag. You might want to probe deeper to find out more about how much they will really champion doc culture, especially if they don’t understand doc culture. Because as I said earlier, most people underestimate the work involved for roles they don’t understand.

Note: There’s a lot of discussion about this post on Linkedin here and on Reddit here.

follow us in feedly