TCCS #6: How to handle managers who do not understand the technical writing role (+ Debunking common myths about Technical Writing)

TCCS #6: How to handle managers who do not understand the technical writing role (+ Debunking common myths about Technical Writing)

The Tech Content Creator Series is a monthly interview series in which I chat with people in technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories to impact, inspire, and motivate you.

For this episode, I spoke to Elisa Sawyer who is a Documentation Architect with over 20 years of extensive technical writing experience. As a technical writer, she has worked with several high-tech companies like Google, Uber, Apple and Visa. She's also an avid member of the writethedocs slack community.

We chatted briefly about how she got into technical writing, what to do when you find yourself working with managers who don't understand the role of technical writers, and also debunked some popular technical writing myths.


Can you briefly introduce yourself?

My name is Elisa Sawyer, and I work as a Documentation Architect. My mother was a concert pianist, and my father was a PhD physicist. My siblings and I watched the local orchestra as if it was a spectator sport and thought the latest in particle physics was what everyone discussed over Saturday barbecue. I love mathematics, sciences, and the arts equally.

How did you get into technical writing and developer documentation? Did you get a writing degree from a university? If you did, what impact did it have on your career?

I was a grant proposal writer for many years before I decided to apply my writing skills to writing for high-tech companies. My Master's degree is in Urban Studies. However, I got a certificate in tech writing that helped me get my first contract for a Silicon Valley company. Later, I enrolled in screenwriting classes through UCLA Extension Writers’ Program.

The technical writing certificate program I enrolled in does not exist anymore. But, I've heard good things about the following programs:

On the writethedocs Slack channel, you once shared an experience of interviewing with managers who did not understand a technical writers' role. Are there any tips you can offer to a technical writer who finds themselves in a similar situation?

I have sometimes had people assume that I should have HTML or JavaScript tags memorized because I write developer-facing documentation. Once, a developer actually thought that I should know how to hand-code HTML. Although I understood his thinking, he made a false assumption and was so arrogant in his ignorance that there was no opportunity to illuminate his understanding of our profession.

For anyone who finds themselves in a similar situation, I don't think there is a single set of guidelines on dealing with managers and team members who don't understand technical writing because all teams have their own culture.

Dispelling common myths associated with the tech writing profession might be helpful in some situations. In addition, pointing to authoritative information on best practices for tech writing, along with conferences for both tech writers and tech writing managers, can be helpful. Some managers/team members actually respond well to helpful tips, and those who don't respond well might simply need time for the information to sink in.

Additionally, during an interview, it is sometimes helpful to ask what problems the manager hopes the writer can solve. The managers' answers to this question can provide information that will help you decide whether you are a good fit.
I have been a contract worker for a long time, so I can't comment on the interview processes for full-time positions. I think that managers and writers involved in interviews for contract roles are able and willing to take risks.

What are the common myths or misconceptions about the technical writing career that you've encountered?

Myth #1: “Why do we need technical writers when developers write self-documenting code.”

Comment: While you can write code with parameters that are easy to understand, I have never encountered a situation where new hires just sit and read through an uncommented code base to quickly understand it.

Myth #2: “We can just wait until the documentation arrives.”

Comment: I was working through a gnarly procedure to write the documentation for several teams of developers when my subject-matter expert made the above comment. I reminded him that if I didn't write it, the documentation would not arrive.

Myth #3: “The docs are basically what we (engineers) told you.”

Comment: A developer commented, in a derogatory way, that the documentation I'd written accurately reflected the information the team gave me. He should have understood that what he said was a compliment, not an insult. The difference between the information the team provided and what I wrote based on their information is that before my work, no one outside the team could effectively understand and use the features they were providing. I organized and documented everything so that even within their own team, everyone better understood how to use the features they offered.

Myth #4: “Technical writers are basically glorified admins.”

Comment: While it’s possible to enter the technical writing profession without a college degree and succeed, technical writing is an actual profession for which we can get advanced degrees. We are often functioning above our degree level. The best technical writers are dedicated to lifelong learning.

Myth #5: “Just pretty things up, and the docs will become better.”

Comment: While good graphics, layout, fonts, and other visual elements can make the communication experience pleasant, great technical writing is much more than pretty.

Do you think someone without a writing degree can have a great technical writing career? Also, do you think someone focused on developer documentation should understand how to code or how it works?

What you need as a writer are good analytic, problem-solving, and writing skills. Success in writing good developer-facing documentation does not depend on knowing how to code.

As a writer, you are not generally solving the same problems as full-time coders. Solving coding problems is the domain of full-time coders. Solving communication problems is the domain of the communications professional.

Also, as a contract technical writer, I have observed that there are many software developers who are confused about the role of the technical writer who focuses on developer-facing documentation. If great developer-facing documentation was easy to write, it would definitely be far more common.

Technical writers are often writing about things they know nothing about. Could you share some tips for how beginner technical writers could get comfortable or get better at writing about things they know nothing about?

Have you ever gotten excited about something that was new to you, and wanted to share your excitement?

Perhaps you decided to do something exciting and unusual like a hot air balloon ride, a cave tour, or kayaking for the first time. You tend to naturally be very aware of everything around you when you are going through that new experience. Because of that heightened awareness, it can be easy to remember many details about the experience.

That kind of heightened awareness of a new environment can help us as technical writers when we are writing about a new subject. We can write authentically about learning a new technology while learning it ourselves.

Lastly, do you have any other general tips or words of advice you’ll like to give technical writers regarding interviewing and excelling in their careers?

It's common for technical writers to continue to improve their technical knowledge and skills. Paradoxically, it's less common for technical writers to continue to reach for advanced writing skills. I have found that taking classes in both fiction writing and writing screenplays for feature films has helped me become a better technical writer. My advice is to treat our profession as any other profession that requires continuing education, and regularly treat yourself to educational opportunities.

More articles you might like:

Get your technical writing career off the ground.

Join over 850+ subscribers just like you. Every two weeks, I'll send you new articles and expert interviews published on the blog, so you'd never miss out. I'll also send you a curated list of other valuable resources on technical writing across the internet, as well as fully-remote technical writing gigs/jobs to help you land your dream job.