I don’t talk about my day job all that often. What I’m doing currently is software development – specifically, I write tools and create infrastructure for a documentation team. This ranges from writing deployment pipelines and build scripts to writing extensions for the writing software we use, to building out sites and wrangling server configurations. I enjoy it, and I like that the role is broad, where what exactly I’m working on can vary a lot from day to day, depending on what needs to take priority. Prior to my current role, however, I was a technical writer – one of the folks writing the docs, and I wanted to talk about that a bit, as I think it’s a great role that I think a lot of folks might overlook.
“Technical” Writer
I think something that might put off some folks is the “technical” part of “technical writer”. It can even be a bit of a bone of contention among the technical writing community, and there’s a not insignificant number who prefer to be referred to as documentarians. So don’t sweat it too much – while there are certainly more technical roles where an understanding of engineering or science or programming (or whatever more technical field you’re writing about) may be necessary, it’s not actually inherent to the role as a whole. What matters is a willingness and ability to explain something. Sometimes it’s an explanation of how it works, sometimes it’s explaining how to do something or use a feature, sometimes it’s explaining what options are available. But if I was going to boil the role down to a one-liner, that’s how I’d define a technical writer: Someone who explains stuff.
I realize that may feel a little broad, but it should be. If you go onto a jobs board and look at technical writer roles, you’ll see a huge range of expectations about what the role will entail (and commensurately, a huge range in what folks are willing to pay – you’ll see roles paying $40k right next to roles paying $150k with the same job title). Some roles require really digging in and understanding a complex topic, others are primarily editorial, taking materials written by subject matter experts and making them consistent and filling in gaps. The only thing that is consistent is you’re trying to help folks wrap their brains around something.
If you find yourself saying “But lots of other jobs are about explaining stuff, like science communicators, or journalists on a technical beat, or textbook writers” – yeah, but that’s a feature, not a bug. “Technical writing” is a broad term, with a broad definition, and the work those other roles are doing can totally count.
If you’re the person who always seems to be writing down the process to do something, or maintains the team wiki, congratulations, that’s technical writing – it may be for an internal audience, but it still counts. If you’re the type who regularly contributes to Wikipedia, or gives useful answers in r/explainlikeimfive, you’ve been doing forms of technical writing.
A day in the life
Let me give an example of what my day to day work looked like as a technical writer (with the caveat that this is just my experience – like I said above, the role can vary a lot depending on what type of material you’re writing about).
On any given day, you could effectively break my work down into three parts:
- Learning: I needed to dig into the product and the features I was writing about, trying things out, seeing how things worked. I’d be exploring the product, as well as reviewing any design documents, work tickets, and code reviews I could, to better understand both how it was working and how it was intended to work.
- Communicating: I’d be working with the developers and the product manager to make sure I was understanding things correctly. Sometimes this would be walkthroughs with the developer, other times it would just be pinging them if I was seeing something I didn’t quite understand or had questions about. This communication is valuable in both directions – it helps me understand, but it also gives them feedback about where the process might be improved (writers are frequently one of the first “users” of the product).
- Writing: Once I’d explored the feature and any available materials, and had a better understanding of what was happening, I’d collect those notes and thoughts and write out an explanation of the feature, along with any procedures, processes, and instructions needed to use the feature. There would be days that this would be actually the smallest part of the job – as one of my old bosses pointed out, “writing three lines didn’t take all day. Figuring out what those three lines needed to be, did.”
The team I was on had dedicated writers per product, so you’d slowly become a bit of a subject matter expert about your assigned product. If there was down time between features, different writers would contribute in different ways – some would pinch hit and help on other products, some would go through and find bits of existing docs that could be improved. (Personally, I ended up fiddling with the writing tools and finding ways we could add new features or improve processes, which is how I ended up eventually transitioning to tools development.)
We operated (and continue to operate) using a “docs-as-code” approach. This means that the writing is treated the same way that developers treat code – it’s managed in repositories, and written in a particular syntax that would be built and turned into whatever format we needed (html, pdf, et cetera). When I started we used an XML-based format called Docbook, though we eventually migrated to a markdown-esque format called Asciidoc. (That said, if you aren’t comfortable with that approach, there are plenty of companies that use other systems, some of which are WYSIWYG or use a CMS. Some even just write in Microsoft Word, though if the final output is intended to be for the web, I personally wouldn’t recommend it.)
“Wait, do I want to do that?”
If you’re looking at what I’ve said so far and are thinking to yourself that sounds easy, great! You might even be wondering why it even needs a separate role – surely you could ask developers to document their own work. The short answer is two things:
- What’s easy for one person is hard for others. I’ve known a lot of developers who were absolutely brilliant at what they did, but would freeze when trying to explain it, or couldn’t separate their internalized knowledge from the work and would end up rabbit-holing or getting overly technical. Being able to explain things well, to people who may not have the same background or experience, is a skill.
- Division of labor. Even if the developer is an excellent communicator and could technically write things up, it’s not always an effective use of their time. In particular these days where there’s an expectation of rapid development and moving on to the next feature, it’s generally more useful to let them focus on their work rather than adding on another task that requires context switching and time to get done.
You might also be wondering if this role is going to get destroyed by AI. And I get that – there’s a lot of hype right now about AI and how it can do all these different things. And there may be some companies that will try to just use AI for their documentation. But it’s actually a more resilient role than you might think. AI needs reliable information to be trained upon – that needs to be written by someone. AI is good at summarization, but it’s not great at understanding which parts to prioritize, and thus far the projects that have attempted to create an AI-based documentation generator largely seem to get walls of text. So while there is some risk for the role, there’s still going to be a lot of companies that are going to prioritize getting it right and recognize that their fancy AI agent needs good material to learn from. You can’t use slop to train your model and then expect to get anything but slop out of it. (I think a lot of the companies that are downsizing in favor of “letting AI do it” are going to regret it before too long, but that’s a topic for a different day.)
So if you’re asking yourself “do I want to do something like that?” I’d say go for it. Maybe you love writing and enjoy explaining stuff – there’s lots of ways to turn that into enjoyable, paying work, and technical writing is one of those. Or maybe you’ve been in a different role but have been doing the internal docs, and want a change of pace – lots of documentarians got started in other areas (QA, support, software engineering, et cetera) and pivoted. Those other skills are an asset in technical writing, not a drawback. Don’t get caught in the trap of thinking your skills aren’t transferrable.
Where to go from here
If you’ve read through this and even thought for a second that it might be something you want to pursue, I wanted to give a few pointers on where to go from here:
- Write the Docs: It’s an online community and also an in-person conference, meant for documentarians and also “friends of the docs” – basically anyone who gives a damn about good documentation. If you have any interest in documentation (as a career or otherwise), this is a fantastic resource. (I’ve been attending the conference since the first one, and when I chose to pivot from QA to technical writing, I was able to get referred through the community to get the job.) As of this writing, tickets to the next conference in May are still on sale, as well.
- Open source docs resources: This is a repo with a bunch of resources for learning how to contribute documentation to open source projects. This is a win-win – open source projects get better documentation, and you get real world experience (and portfolio work!).
- Google’s Technical Writing courses: A set of resources for learning how to get into technical writing and writing good docs.
- Reach out, I’m happy to answer any questions you might have.