What is technical writing?

But before understanding what it is, why should you care? 

My personal hot take is tech writing is an under-considered gem in the corporate tech world. You don’t have to be on-call like a software engineer. It’s better paid than other writing roles like UX, copy, or marketing. And involves less nagging and fewer meetings than a TPM. Because the combination of skills required is unique (but developable for many people) it can be a less competitive space (smaller pond, bigger fish).

What is technical writing?

Newspapers and blogs are for information. Novels are for entertainment. Technical writing is to help someone complete a specific task.

IKEA assembly instructions are a kind of technical writing. But in terms of the modern job market, the most common example of technical writers are the people who draft, structure, and polish a SaaS company’s API integration guide aimed at helping their customers call their API.

The goal of technical writing is to be clear, concise, and get your user through their task as quickly as possible. This requires the ability to ask the right technical questions—what’s this for, why does someone need it, what users won’t this work for, how do you test it’s working as expected. And then take that information and present it in a readable, organized, logical, and crisp way that speaks on an intuitive level to software engineers and how they think.

What kind of roles are there?

I’ll limit this to the software space as that’s what I know best.

Technical writing roles can fall into a few different buckets depending on the audience you write for. Most roles are external facing—you author API references, how-tos, and integration guides to help your customer’s use your company’s products.

For more technical products, docs might cover what they do and how to use them more generally (think Kafka, graphQL, Prometheus).

External tech writing can also include support content focused around debugging or resolving common user issues (and might cover less technical issues like how to configure a certain flow via UI vs via CLI/code).

One downside of external facing work is that writers may be subject to deadlines for product launches. And everyone always leaves documentation to the last minute, assuming “that’s the easy part” much to the writer’s (and user’s) chagrin.

Much rarer are internal facing technical writing roles, where you help software engineers within a company write better documentation to improve adoption of tools they’re building, to reduce the time engineers spend answering questions from other engineers, to help incidents get resolved faster, and generally to improve developer productivity.

My former manager Dave Nunez, has a great deep dive on why internal documentation is vital: Investing in Internal Documentation: A Brick-by-Brick Guide for Startups.

Personally, transitioning from software engineering to an internal facing technical writing role was perfect—being internal facing meant we could move fast, take an iterative and creative approach, and add in touches of whimsy and humor to get and keep a user’s attention. I could immediately leverage my ability to think like, relate to, and talk with software engineers. And I had direct access to my users to understand what they needed and whether what we were doing was working. I also got to do lots of teaching others to write (office hours, curriculum development, templates, style guides) in addition to writing myself, which I really enjoy. 

This doesn’t sound like that much fun?!

Fun is in the eye of the beholder. And there’s likely a ceiling on how fun any job can be.

Compared to software engineering

I love getting to talk to and think like a software engineer and enjoy finding creative ways to convince them writing matters. Pattern matching, building mental models, and thinking about/understanding software at the architectural level is fun.

I don’t have to write yet another CRUD API, write tests, or implement detectors.

I get to interview super smart engineers about the things they know best. And then I have the freedom and creativity to explain the things I learned in words. I get to help people directly—the subject matter expert (SME) will get to work on other things instead of answering repetitive questions and other engineers will be unblocked and able to complete their tasks more easily.

I’m not going to break anything or take down a service. I’m not on call and don’t ever get paged.

Unlike coding, where after 4 hours of work you might be in a worse state than when you started (your devbox broken, an upgrade borked), with writing input generally equals output. After 4 hours, I almost certainly have a solid draft, even if it’s not perfect and will need further revision with fresh eyes.

And after lots of struggle, when you finally lock in on the right structure for information either within a doc or across a series of docs (information architecture in tech writer lingo) it’s as satisfying as winning at Tetris. For me, that’s the same endorphin hit as solving a logic puzzle on the LSAT or fixing a bug with code.

Compared to writing and legal jobs

It’s not adversarial. Despite my background as a collegiate debater, I’ve learned I prefer a collaborative environment where we’re all (at least theoretically) rowing in the same direction.

Big tech job perks—salary, stock, (relative) stability.

There aren’t that many people with both technical and writing skills. There are also fewer tech writing jobs. But the competitive landscape is generally more favorable than many writing roles.

High novelty. I’m always learning about something new. The average project length is short. And people actually read what I write!

What other kinds of writing roles are there?

Lots!

Arguably law, grant writing, proposal writers (for example for Requests for Proposals – RFPs), scientists, science journalism, and financial writing are types of technical writing and could be framed as relevant experience to technical writing roles, but there’s lots of other writing jobs too.

Copywriting (blogs, white papers, case studies, brochures), UX writing/content design (the words that help users navigate a user interface) are two other common writing roles that most tech companies will have.

Alright, I’m curious and want to know more. What’s the interview process like? How do I pivot to tech writing? What are the pros and cons of tech writing? What about salary? What’s a day in the life like?

Great questions—these require their own post, coming soon!