If you’re interested in becoming a technical writer, or are new to the field and want to deepen your skills and awareness of the field, this blog post is for you.

What do technical writers actually do? #

Technical writers can do a lot of different things! People in technical writing write how-to documentation, craft API reference documentation, create tutorials, even provide user-facing text strings to engineers.

Ultimately, technical writers:

• Research to learn more about what they are documenting.
• Perform testing to verify that their documentation is accurate and validate assumptions about the product.
• Write words that help readers achieve specific learning objectives and that capture what the writer has learned in the research and testing processes.
• Initiate reviews with engineers, product managers, user experience designers, quality assurance testers, and others to validate the accuracy, relevancy, and utility of the content.
• Advocate for the customer or whoever uses the product or service being documented.

The people reading what technical writers have produced could be using software they’ve purchased from your company, evaluating a product or service they are considering purchasing, undergoing a required process controlled by your organization, writing code that interfaces with your services, configuring or installing modifying hardware produced by your company, or even reviewing the documentation for compliance and certification purposes. Your goal, if you choose to accept it, is to help them get the information they need and get back to work as soon as possible.

Identify what you want from your career #

Some general career-assessment tips:

• Identify what motivates you and what challenges you.
• Identify what type of team environment you want. These are loose descriptions of types of team environments that are out there:
  • A large highly-collaborative team with lots of interaction
  • A distributed team that is available for questions and brainstorming as needed, but largely everyone is working on their own thing.
  • A small team that collaborates as needed.
  • A team of one, it’s just you, you are the team.

Is technical writing a good fit for you? #

• Do you enjoy explaining things to other people?
• Do people frequently ask you to help explain something to them?
• Do people frequently ask you to help them revise content for them?
• Do you care or enjoy thinking about how to communicate information?
• Do you identify when things are inconsistent or unclear and ask people to fix it? (Such as in a UI implementation, or when reviewing a pull request)
• Do you enjoy problem-solving and communication?
• Do you like synthesizing information from disparate sources, from people to product to code to internal documentation?
• Do you enjoy writing?

My background and introduction to technical writing #

I started in technical support. In college I worked in desktop support for the university, wandering around campus or in the IT shop, repairing printers, recovering data from dying hard drives, running virus scans, and updating software. After graduation I eventually found a temp job working phone support with University of Michigan, managing to turn that position into a full-time permanent role and taking on two different queues of calls and emails.

However, after a year I realized that was super exhausting to me. I couldn’t handle being “on” all day, and I found myself enjoying writing the knowledge base articles that would record solutions for common customer calls. I wrote fifty of them by the time I discovered a posting for an associate-level documentation specialist.

I managed to get that position, and transferred over to work with a fantastic mentor that taught me a ton about writing and communicating. After a few years in that position, writing everything from communication plans (and the accompanying communications), technical documentation, as well as a couple video scripts, I chose to move to California.

With that came another set of job hunting, and realizing that there are a lot of different job titles that technical writing can fall under: UI writer, UI copywriter, technical writer, documentation specialist, information developer… I set up job alerts, and ended up applying, interviewing, and accepting an offer for a technical writing position at Splunk. I’ve been at Splunk for several years now, and recently returned to the documentation team after spending nearly a year working in product management.

Where people commonly go to technical writing from #

Technical writers can get their start anywhere! Some people become technical writers right out of college, but others transition to it after their career has already begun.

As a technical writer, your college degrees doesn’t need to be in technical writing, or even a technical-specific or writing-specific field. I studied international studies, and I’ve worked with colleagues that have studied astronomy, music, or statistics. Others have computer science or technical communication degrees, but it’s not a requirement.

For people transitioning from other careers, here are some common starting careers:

• Software developers
• UX practitioners
• Technical support

That’s obviously a short list, but again if you care about the user and communication in your current role, that background will help you immensely in a technical writing position.

Prepare for a technical writing interview #

Prepare a portfolio of writing samples #

Every hiring manager wants to see a collection of writing samples that demonstrate how you write. If you don’t work in technical writing yet, you might not have any. Instead, you can use:

• Contributions you’ve made to open source project documentation. For example, commits to update a README: https://github.com/yahoo/gryffin/pull/1
• How-to processes you’ve written. For example, instructions for performing a code review or a design review.
• A blog post about a technical topic that you are familiar with. For example, a post about a newly-discovered functionality in CSS.
• Basic task documentation about software that you use. For example, write up a sample task for how to create a greeting card in Hallmark Card Studio.

Your portfolio of writing samples demonstrates to hiring managers that you have writing skills, but also that you consider how you organize content, how you write for a specific audience, and the level of detail that you include based on that audience. The samples that you use don’t have to be hosted on a personal website and branded accordingly. The important thing is to have something to show to hiring managers.

Depending on the interviewer, you might perform a writing exercise in-person or as part of the screening process. If you don’t have examples of writing like this, that’s a good reason to track down some open source projects in need of some documentation assistance!

Learn about the organization and documentation #

Going in to the interview, make sure you are familiar with the organization and its documentation.

• Read up about the organization or company that you are interviewing with. If you can, track down a mission statement for the organization.
• Find the different types of documentation available online, if possible, and read through it to get a feel for what the team might be publishing.
• If the organization provides a service or product that you’re able to start using right away, do that!

All of these steps help you better understand how the organization works, what the team you might be working on is producing, and demonstrates to the interviewer that you are motivated to understand what the role and the organization are about. Not to mention, this makes it clear that you have some of the necessary skills a technical writer needs when it comes to information-gathering.

Questions you might want to ask #

Find out some basic team characteristics:

• How many other technical writers are at the organization?
• What org are the technical writers part of?
• Is there a central documentation team or are the writers scattered across the organization?
• How distributed is the documentation team and/or the employees at the organization?

Learn about the documentation process and structure:

• What does the information-development process look like for the documentation? Does it follow semi-Agile methods and get written and researched as part of the development team, or does information creation follow a more waterfall style, where writers are delivered a finished product and expected to document it? Or is it something else entirely?
• Are there editors or a style guide?
• Do the writers work directly with the teams developing the product or service?
• What sort of content management system (CMS) is in use? Is it structured authoring? A static-site generator reliant on documentation files written in markdown stored next to the code? A wiki? Something else?

Find out how valuable documentation is to the organization:

• Do engineers consider documentation vital to the success of the product or service?
• Do product managers?
• Do you get customer feedback about your documentation?
• What is the goal of documentation for the organization?

Some resources for getting started with technical writing #

Books to read #

These books cover technical writing principles, as well as user design principles. None of these links are affiliate links, and the proceeds of the book I helped author go to charity.

• The Product is Docs by Christopher Gales and the Splunk documentation team
  • Yes, I helped.
• Every Page is Page One by Mark Baker
  • This book is a great introduction and framework for writing documentation for the web.
• Developing Quality Technical Information by Michelle Carey, Moira McFadden Lanyi, Deirdre Longo, Eric Radzinski, Shannon Rouiller, and Elizabeth Wilde.
  • This book is a great resource and reference for detailed writing guidance, as well as information architecture.
• Design of Everyday Things by Don Norman
  • The classic design book covers user-focused principles that are crucial to writing good documentation.

This is an intentionally short list featuring books I’ve found especially useful. You can also consider reading Scenario-Focused Engineering: A toolbox for innovation and customer-centricity, Nicely Said: Writing for the Web with Style and Purpose, Content Everywhere: Strategy and Structure for Future-Ready Content, Design for How People Learn, and Made to Stick: Why Some Ideas Survive and Others Die.

Articles and blogs about technical writing #

I like following resources in RSS feeds to get introduced to good thinking about technical writing, but not all good content is new content! Some great articles that have helped me a lot:

Blogs to follow (intermittently updated) #

• Beth Aitman’s http://uiwriting.tumblr.com/
• Mark Baker’s http://everypageispageone.com/
• Tom Johnson’s http://idratherbewriting.com/
• Nielsen Norman Group articles: https://www.nngroup.com/articles/

Great articles about technical writing #

• How Chunking Helps Content Processing by Kate Moran for Nielsen Norman Group
• Writing great documentation by Taylor Singletary
• Users’ Advocate: Balancing Just-in-Time Support Docs and Customer Experience by Neal Kaplan (who I now work with)
• How can technical writers cut through engineering jargon and decode complex information? by Tom Johnson
• Top 10 Most Frequently Asked Questions about Technical Writing by Tom Johnson
• A little thing about release notes by the Slack team
• How to write a great error message by Thomas Fuchs
• What is the technical writer’s role in content marketing? by Tom Johnson
• Writing truthful documentation by Tom MacWright
• Inverted Pyramid: Writing for Comprehension by Amy Schade for Nielsen Norman Group
• Plain Language Is for Everyone, Even Experts by Hoa Loranger for Nielsen Norman Group
• Break Grammar Rules on Websites for Clarity by Hoa Loranger for Nielsen Norman Group

Other web resources #

Twitter is a great resource for building a network of people that care about documentation. If you use it, I recommend searching for people who commonly tweet with #writethedocs.

Write the Docs is a conference and community founded by Eric Holscher and maintained by a brilliant set of volunteers!

The Write the Docs Slack workspace is fairly active, and includes channels for job postings, career advice, as well as current discussions about trends and challenges in the technical writing world.

Some talks from the conference I recommend checking out are visible on YouTube:

• Write the Docs Portland 2017: Error Messages: Being Humble, Human, and Helpful… by Kate Voss
• Write the Docs Portland 2017: Caring Systems: Documentation as care by Amelia Abreu
• Write the Docs Portland 2017: Even Naming This Talk Is Hard by Ruthie BenDor
• Write the Docs Portland 2017: Start with the tasks, not the endpoints by Sarah Hersh
• Write the Docs Portland 2016: Write the Readable README by Daniel Beck
• Write the Docs Portland 2016: Copy That: Helping your Users Succeed with Effective Product Copy by Sarah Day
• Write the Docs Portland 2016: 7 Values of Effective Tech Writing Teams by Joao Fernandes
• Write the Docs Portland 2016: Oops, I Became an Engineer by Tara Scherner de la Fuente

There are playlists for 2018 (which I did not attend) and earlier years as well on YouTube, so dig around there and find some more resources too if watching videos is useful to you!