I’m often asked “what does a technical writer do?” and usually respond by describing where I work, the goals of my projects, the kind of work they entail, and how I spend my time. But when I was asked to spend an hour discussing technical writing with a group of university students participating in Google’s Tech Exchange program, I thought it might be time to put a little more thought into it and write it down. Honestly, this article has been percolating in my mind for quite some time.

These are my thoughts and opinions based on my years of experience as a tech writer. Other writers are going to have different experiences and opinions, which I recommend that you search out and read to give you a well-rounded understanding of the discipline. You probably won’t be surprised to discover that each of us has a slightly—sometimes drastically—different perspective, but every one of them is valid and informative.

We keep moving forward, opening new doors and doing new things because we’re curious and curiosity keeps leading us down new paths. ~Walt Disney

Bio

When I attend or listen to a presentation, I’m always interested to know more about the speaker and their experiences. Since this article is based on a presentation I gave to university students, I’m including my biography slide.

As of this writing (June 2023), I have seven years experience as a technical writer, and sixteen years before that as a systems engineer, team lead, software engineer (developer), and software tester. My bachelors degree is in Accounting, which I practiced for a few years before realizing it wasn’t for me and switched to the information technology (IT) field—this was inspired by my brother who had recently left the U.S. Navy and began his career in IT.

What is technical writing

Before I describe the work of a technical writer or what their day might look like, let’s establish the purpose of technical writing. If you search “what is technical writing” you’ll find plenty of accurate and detailed descriptions, but I boil it down to the following.

Technical writing is helping people understand complex ideas and technology.

This is what I always come back to when I’m explaining my work to someone. It’s also what led me to the discipline, pulling me away from software engineering. I enjoy learning technologies and helping people; putting the two together was a turning point in my career.

To break it down a bit further, technical writers spend much of their time doing the following.

• Learning (often complex) technologies
• Understanding how people will use those technologies
• Explaining them in useful ways for the audience

Skills of a technical writer

I switched from software engineering to technical writing because the skills I excelled at—and enjoyed—mapped to those most needed by technical writers.

• Communicate - It’s not just about the writing, although that is important
• Collaborate - With people and teams across different disciplines (engineering, program management, & more)
• Curiosity - Always be learning
• Empathy - Put yourself in your readers place
• Planning - Plan the work
• Organization - Work the plan
• Research - Know where to find answers or who to ask
• Technical aptitude - Able to understand, interpret, and explain concepts and instructions
• Practice, practice, practice - Self explanatory :)

Now that you’ve read the list, let’s go into a bit more detail about each of the skills.

Education is not something you can finish. ~Isaac Asimov

Communicate

As a philosophical-minded person, I feel strongly that communication is the key to much in life. If you consider your relationships, personal or professional, their quality often hinges on how well the two of you communicate.

Communication is about more than words on a page and that’s what makes it so important for everyone, not only technical writers. It’s a skill—or set of skills—that can be learned, practiced, and improved. State your message clearly and succinctly, while understanding your audience’s perspective and preferences, and do so in a timely manner depending on the situation. Those are merely the basics of effective communication.

Although we’re writers by title and trade, technical writers need to be able to communicate effectively across job disciplines, teams, and even companies, using all the methods available to us.

Collaborate

Technical writers often find ourselves collaborating across multiple disciplines and can become the glue that brings people, ideas, and projects together. We work closely with engineers to understand how the product works, user experience researchers (UXR) to learn how people use the product, product managers to know what product features are scheduled for the future, program managers to know features’ status and release dates, user experience writers (UXW) to synchronize the technical documentation with the product labels and descriptions, and more.

When we collaborate with different disciplines across multiple teams, the strength and effectiveness of those relationships have a large impact on the projects.

Collaboration depends on consideration. You have to extend your hand to the person you’re working with. ~Dave Grohl (Off Camera with Sam Jones)

Curiosity

While some might describe curiosity as a personal characteristic, I think it’s also a skill that you can explicitly develop. The drive to understand how something works can come from an interest in the subject matter, or it can come from a prescribed expectation that you need to learn about something before you can use it. Regardless of the reasoning, being curious serves a technical writer well.

When you’re curious, you ask questions until you understand the answers and that’s key to successfully explaining complex technologies.

Empathy

It’s imperative that a technical writer understand the perspective of their audience. By empathizing with our readers, understanding how they interact with the product or technology, we bridge the gap between what people expect and what they can do with the product.

Planning

Plan the work and work the plan. ~Unknown

Without a plan, you’re herding cats. That doesn’t mean you must have a plan, but it makes things easier throughout the project. There are several variables and considerations when writing a technical document or set of docs. Planning for those ahead of time allows you to focus on doing the tasks and coordinating them, instead of figuring out what they are as you go.

I’ve worked through documentation projects both ways, with and without a plan. Creating a plan ahead of time forced me to think through the goals, non-goals, audience, use cases, architecture, tasks, timelines, and more, allowing me to be more agile when things went awry—which they often do.

Here’s a doc plan template that I created for myself and use regularly, which combines aspects I liked from several other templates.

Organization

This is the work the plan portion of the previous quote. Similar to having a plan, being organized allows you to focus on doing the tasks, creating the content, and coordinating everything. Being organized also applies to your communication with peers, partners, and stakeholders. Keeping up with and staying on top of collaborative efforts with different people is challenging even when you’re organized. Without being organized, you’re back to herding cats.

Research

Akin to curiosity, research is a skill directly associated with a technical writer’s ability to learn technologies. Knowing where to find the answers you need or who to ask for help drastically improves the efficiency of our time. Research takes time, and that’s expected to lead you down unintentional or unproductive pathways at times, but you want to minimize those occurrences. Having said that, sometimes those unexpected paths are the ones that yield the most productive results…so don’t arbitrarily limit your exploration.

Technical aptitude

Although this skill is towards the end of the list, it’s extremely important. Let me be clear, I’m not referring to an ingrained talent to understand technology, where you must be someone who just gets it. I firmly believe that technical aptitude is a skill we can develop through curiosity, research, exposure, and practice. Get in there with the product, feature, or technology, do your best to understand it, and play around with it enough to build a familiarity. Once you’ve done that, parts of what you learn will apply to other technologies and help you learn them faster and more efficiently. Doing this, you can develop and improve your technical aptitude over time.

Practice, practice, practice

While this isn’t necessarily a skill, it’s imperative that you build the habit of practicing the skills previously described. Like anything, the best way to improve is to practice, whether it’s your jumpshot or how well you communicate with stakeholders. The more you do it, the easier it will be and the better you’ll be at doing it. Practice and then practice some more!

Day in the life

When I was an engineer and interested in switching disciplines, I asked a friend who had 10 years of experience as a technical writer, “what do you do?” Here’s their answer:

About one-third of my time is spent doing program management (PgM) work, another third with engineering (SWE) and testing work, and the remaining third is actually writing docs (TW).

Their description has stuck with me all these years. It’s practical, succinct, and accurate, especially for those of us in the software industry who are familiar with each of the disciplines. Technical writers spend their time collaborating, engineering, and writing.

Collaborate (PgM)

As previously described in the skills section, collaboration is imperative to being successful as a technical writer. I’d posit that it’s a primary function of a program manager, hence the role comparison.

A typical workday involves communicating openly and in a timely manner with subject matter experts, stakeholders, and other writers about the project’s status and any issues that arise. Technical writers work closely with engineers and subject matter experts to gain a certain level of understanding of the product or features. Like most, writers often have more requests and work than we can fit into a regular day or week, which requires us to prioritize and manage the workload with our peers and stakeholders.

Engineer (SWE)

You might think that this functionality relies heavily—or even mostly—on the technical aptitude skill, but don’t underestimate the impact of curiosity, communication, empathy, and research.

Technical writers have to learn the technology, product, or feature well enough to explain it to others. This often means interviewing engineers and then testing the product yourself in a sandbox environment by writing some code—perhaps with help from a SME. By going through this process, writers gain an understanding of what customers will experience and how to best explain it to them. We’re often one of the first people using the feature, finding bugs, and working through development hiccups, which can translate into the documentation we create.

Write (TW)

This might be surprising, but writing the document—or documentation set—is often the last thing a technical writer does.

Before we can begin writing, we need to gain a sufficient understanding of the technology and how to use it. During this initial timeframe, we’ll begin planning and organizing the work in a doc plan (template), based on estimates from collaborating with peers and stakeholders. As we write the documentation, we’ll follow style guides, adhere to company and industry standards, and iterate on the content frequently based on feedback and reviews from subject matter experts and other writers or editors.

The documentation we publish is the tip of the iceberg, with the program management, engineering, and much of the writing work underneath the metaphorical water, never to be seen by the readers.

What I like about technical writing

When I finished my presentation to the Tech Exchange participants, I asked for feedback from a friend and fellow tech writer who attended. They advised me to include what I like about technical writing and what makes it fun, to help the audience understand more about my motivation.

I like writing. I like technology. Putting the two together was a no-brainer that took me 16 years to figure out.

First and foremost, the people are my favorite part of being a technical writer. Honestly, I can say this about each position in my career, but, admittedly, I feel a special connection with other writers, moreso than I did with engineers. Writers typically value the skills that I previously outlined, often come from unexpected professional backgrounds, encompass diverse personal life experiences, and share a love for learning.

I can shake off everything as I write; my sorrows disapper, my courage is reborn. ~Anne Frank

Writing has been instrumental to my life since I was a teenager. I’ve written short stories and—arguably bad and angsty—poetry; journalled about my emotional highs and lows; blogged about fatherhood, software development, technology, and life-stuff; and written short, auto-biographic details of various points in my life. From a professional, educational, and learning perspective, I’ve always leaned towards notes and documentation as my go-to for keeping or transferring information. Writing is an integral part of who I am and getting to do that as my primary job function brings me a lot of joy.

Always be learning

Combining my curiosity with a job where I’m expected to learn new things is a recipe for fun. While they call it work and not play for a reason—a phrase often heard from my dad—I sincerely enjoy digging into something new and trying to understand it as best I can. On a personal note, my curiosity and love of learning is one of the reasons I’m an avid reader (check out my reading list), which I believe contributes to my success as a technical writer.

Not all readers are leaders, but all leaders are readers. ~Harry S. Truman

It wasn’t until later in my career that I realized how much I enjoy helping others. I like knowing that my work helps someone get through a tough moment of their code failing or providing that ah-ha moment when they finally understand a complex concept. While it might not necessarily fit into the category of fun, it’s rewarding and a large part of my motivation.

Find joy in your work

Discussing what I like about technical writing brings up the concept of how we feel about our work. Here’s my personal theory on job satisfaction.

To experience joy in your work, focus on the skills you enjoy and build your proficiency with them.

I prefer this philosophy to do what you love, advice that we hear so often, and here’s why:

• The word love has significant weight to it and can have a powerful impact on our emotional health. Attaching love to our work can create emotional highs and lows that we have little control over and affect our work-life balance.
• The mentality of do what you love directly and deeply connects your job to your identity and, subsequently, your community. It’s great to have a sense of community with our co-workers, but it shouldn’t be the primary or only community in our life.
• By focusing on our skills, learning, and improving them, we intrinsicly find joy in our behavior and accomplishments. Research over the last few decades has proven that this is a sustainable way to feel joy, instead of pursuing the ambiguous idea of happiness.
• Words matter. I prefer to focus on joy instead of happiness. Joy is an inner feeling—usually associated with meaning or purpose—whereas happiness is an emotion. Joy can be constant, while happiness is temporary.
• Pragmatically speaking, skills are transferable between jobs, making role transitions more accessible to you over the length of your career. By focusing on your skills—especially the ones you enjoy—you can identify where they apply to all kinds of different jobs and industries, which opens up a world of opportunities.

Q&A

The following are answers to questions I’ve been frequently asked about technical writing, not limited to the recent presentation that initiated this article. Admittedly, technical writers either love or hate the FAQ section of any doc set, so I know I’m tempting fate by putting this here. :)

Keep in mind that these are based on my experience writing documentation for the software industry.

How can I transition into technical writing?

Write! Find opportunities in your current position, job, or company to write documentation and gain some experience while creating a portfolio. While doing so, be sure to follow the suggestions in How can I improve my writing skills?.

Focus on the skills! Review the skills of a technical writer and think about how you demonstrate them in your current role. Try to increase the areas of your day-to-day work that use these skills so that you can speak to them on your resume and during interviews.

Create a portfolio! If you’re able to create documents as part of your current role, determine if they can be shared publicly and included in your writing portfolio. If only parts are confidential, you might try scrubbing them of that information and sharing them publicly, but I recommend that you error on the side of caution when doing so.

Take a certification course! Before I had official experience as a tech writer, I often received the same reaction to my applications: come back to us when you have a year or two of experience. I was able to get over this hurdle by taking a certification course. Here are a few to investigate.

• Technical Writing Certificate Program at the Tombolo Institute at Bellevue College
• UW Certificate in Professional Technical Writing
• UC Berkeley Certificate in Technical Communication.

How can I build a writing portfolio?

• Include documentation you’ve written in your current role, per my recommendation in How can I transition into technical writing?.
• Think of a technical task or project you’ve done or want to do and document it. This is how I came up with the writing sample describing how to upload and backup files to Amazon S3 with PowerShell.
• Find an existing document and rewrite it. This is an opportunity to make changes to the content’s flow, correct assumptions, and use your own tone of voice. It’s also an opportunity to explain why you made the changes, while maintaining a positive attitude towards the original. Instead of saying “it sucked” try to point to objective reasons, such as “during my testing I discovered that they missed a crucial step” or “I had trouble understanding the analogy they used to explain the concept and wanted to try a different one.” If you do this, state clearly that you’re rewriting someone else’s work so that the reviewers don’t mistake it for your original writing.
• If you have a side project, such as creating a mobile app, document it as though you’re doing so for customers or your imagined team of engineers, product managers, and program managers.
• Contribute to an open source project. Honestly, this is much more difficult than many realize. I received this advice, but I couldn’t find a project that I understood, needed documentation, and had a clear entry point for me to contribute. The barrier to entry was too high, especially as an inexperienced writer.

What should I include in my portfolio?

More isn’t necessarily better. A reviewer or recruiter will have limited time to review your portfolio, so you want to present the breadth of your experience while keeping them to the point. I recommend the following.

• Provide 3-5 documents
• Each document should be 5-10 pages in length
• The set should include 2-3 of the following types of documents (with at least one or two of the ones recommended):
  • [Recommend] How-to - a task-based set of instructions that arrive at a clear goal
  • [Recommend] Conceptual - explains a technology
  • [Recommend] Tutorial - how to complete a task from start to finish with guaranteed success
  • API library - how to use an API with a client library
  • Best practices - provide recommendations for a common customer goal
  • Quickstart - guidelines for creating or doing something new quickly
  • Bulletin - an issue that needs to be publicized to customers or stakeholders
  • Troubleshooting - guidelines for how to deal with a specific problem or issue

You can view my portfolio at todhilton.com/technicalwriting.

How can I improve my writing skills?

Practice, practice, practice! And while you’re practicing, do the following.

• Familiarize yourself with industry best practices for things like grammar, punctuation, capitalization, formatting, abbreviations, accessibility, localization, and more.
• Keep your writing clear, succinct, accurate, and use a conversational tone. Avoid wordy prose and making the tone too informal or formal, find a nice middle ground.
• Understand how to follow a style guide, such as the Google developer documentation style guide.
• Discuss writing with other writers and editors. For example, check out the Write the Docs communities.
• Read your documents out loud. This might sound silly, but it’s helpful when self-editing and trying to maintain a conversational tone.

How can I get experience writing technical docs?

If you’re transitioning from an existing role or job, see How can I transition into technical writing?.

If you don’t have opportunities to write in your existing role, I recommend reviewing the suggestions in How can I build a writing portfolio?.

Do I need to know how to code?

Yes, at least to some degree. The more programming knowledge you have, the more opportunities you’ll find.

To be a technical writer in the software industry, you should be familiar enough with a programming language to understand sections of code when reading it. It’s also likely that you’ll be writing small sections of sample code, referred to as code snippets. The complexity of the code snippets vary greatly and engineers can help create and review them, also providing writers the opportunity to learn as they’re creating the docs.

The coding ability of technical writers spans a broad spectrum of experience and capability. There are writers who can code as well as the engineers they work with, and writers with minimal programming knowledge or experience. The same can be said for the products and technologies we write about. There are products that require little coding and others that are extremely technical, where writers spend a significant amount of effort on code samples.

Do I need to love writing?

No, but I think it helps.

What other types of writing jobs are available?

This is not an exhaustive list, rather some examples of other writing-related jobs in the software industry.

• User experience (UX) writer
• Technical editor
• Instructional designer
• End-user documentation writer
• Marketing content writer

What can engineers do to work better with tech writers?

I sincerely appreciate the thoughtfulness of this question—admittedly, it caught me off guard when I received it.

Respect the writer and their work. When our interactions across disciplines are rooted in respect for each other, we can build a relationship based on mutual trust that allows each of us to flourish and do our best work. Knowing that the engineer respects them and their work, creates confidence in the writer, allowing them to move through the writing process effectively and efficiently.

I’ve heard stories of companies and teams where the tech writers had to constantly prove their value to the engineers. Not only is that exhausting, but it consumes much of your time that you could be using to create great documentation that ultimately makes for a better customer experience. Fortunately, my experiences with engineers have been exceedingly positive and respectful during my time as a tech writer.

How does technical writing differ from the documentation work done by engineers?

Documentation created by a technical writer includes the benefits of their experience and knowledge as professional communicators.

An engineer’s primary focus is to create an application, program, or the like. Whereas, a technical writer’s focus is to help people understand complex ideas and technology. They’re different jobs and while crossover happens, the success of doing so is mixed.

When an engineering team has support from technical writers they play an integral role in the documentation process by sharing their domain knowledge, reviewing the docs for accuracy, and sometimes creating initial rough drafts.

When the engineering team is responsible for the technical documentation, in addition to their development responsibilities, it can create opposing priorities and time constraints that reduce the effectiveness, efficiency, and quality of both the product and the documentation.

How does engineering differ from technical writing?

The short answer is that they’re different jobs with different focuses. Many of the skills crossover, such as a technical writer who is proficient at coding or an engineer with excellent communication skills will both be more effective in many positions. Yet, each role has different priorities and produces different end products.

Also see How does technical writing differ from the documentation work done by engineers? for more on this topic.

Here are a few fun personal questions from the presentation’s attendees.

Who’s your favorite superhero?

Spiderman! Since I was a little kid, I’ve loved his ability to go anywhere he wants using his bare hands and feet. As I grew older and better understood his story, I loved that he was a nerdy teenager with an altruistic desire to help people.

What’s your favorite comic book series?

There are so many good ones, but narrowing it down to a few I’d callout Saga (by Brian K. Vaughan & Fiona Staples), Monstress (by Marjorie M. Liu & Sana Takeda), and Fables (by Bill Willingham).

Resources

The following are some useful resources for learning more about technical writing. This list is far from exhaustive, as your favorite search engine will reflect when you ask questions such as “what is technical writing?” or “how to become a technical writer?”

• [Article] Brief introduction to Technical Writing
• [Article] What is Technical Writing?
• [Article] Becoming a Technical Writer (Google)
• [Article] What does a software technical writer do?
• [Book] Modern Technical Writing: An Introduction to Software Documentation, by Andrew Etter
• [Book] On Writing Well: The Classic Guide to Writing Nonfiction, by William Zinsser
• [Blog] FFeathers, by Sarah Maddox
• [Blog] I’d Rather Be Writing, by Tom Johnson
• [Course] Google’s Technical Writing Courses
• [Jobs] Write the Docs job board
• [Salary] Technical Writers @ U.S. Bureau of Statistics
• [Tool] Doc plan template
• [Tool] Google developer documentation style guide

Presentation slides

Here are the slides from the presentation I gave on May 17, 2023 to university students participating in Google’s Tech Exchange program. There are more explanations and resources listed in the speaker notes.

A big heartfelt thank you to those who attended my presentation! I appreciate you taking the time out of your busy conference schedule to listen to me talk about technical writing, a discipline that I thoroughly enjoy—and enjoy talking about.