So you want to be a technical writer

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)

Great articles about technical writing

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:

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!

Accessibility, Sound, and Communication

My birthday was yesterday! To celebrate, I ate an overly large and overly expensive steak and sorely undercooked brussels sprouts. Do yourself a favor and always roast brussels sprouts until they are caramelized and crunchy, then put some reduced apple cider and maple syrup on top. YUM!


Technology, while making the world more accessible than it has been in the past, has a lot of work to do for people with disabilities. A huge example of this is the shortcomings in OCR (optical character recognition) technology. In short, OCR sucks. And when we use it to simplify our lives (make a PDF into something that I can copy-paste into a text file), then when it fails it’s a minor inconvenience, and a silly one at that.

Just one problem. Continue reading

Reading, Drones, and Georgie Washington

Americans are still reading books, Internet and all! Younger Americans are actually reading more than older generations, which could be partially due to the fact that with the rise of texting and social media, so much of our communication is text-based, so everyone is doing a lot more reading (and writing) in order to communicate with their friends. The original study is linked in that article and in this graph:

What are some other ways to get people to read books?

Well it helps a lot if your college library not only tells you the call numbers of the book, but it gives you precise directions to the location of the book, which is pretty awesome. Much more useful when navigating a giant library, like I have access to at the university I work at, as opposed to the smaller library at the university I actually attended.

Continue reading

Children, Espionage, and Pain

Here’s what was important this week…

If you have a child abroad, and you’re a U.S. citizen, you can get your child U.S. citizenship as well. However, as Tori Marlan investigates  “the rules that determine what babies can become citizens seem to be butting up against the modern circumstances under which Americans are having babies.” Most notably, modern practices that involve children being born before marriage, or through fertility treatments, or to same-sex couples. Proof is needed to prove that the child is “born of” the U.S. citizen–implied in heterosexual couples, but not as much for homosexual couples. Alexis Madrigal explores further implications that the future of reproductive technology will have for how we define parenthood.

In an unprecedented move, the U.S. indicted 5 members of the Chinese military on economic espionage charges.

As security expert Bruce Schneier points out, we’re guilty of nearly the same:

“The only difference between the U.S. and China’s actions is that the U.S. doesn’t engage in direct industrial espionage. That is, we don’t steal secrets from Chinese companies and pass them directly to U.S. competitors. But we do engage in economic espionage; we steal secrets from Chinese companies for an advantage in government trade negotiations, which directly benefits U.S. competitors. We might think this difference is important, but other countries are not as as impressed with our nuance.”

And James Surowiecki writes for the New Yorker on the fact that the U.S. got its start as an industrial power by engaging in just that kind of espionage, to the point where “State governments financed the importation of smuggled machines.”

As Surowiecki concludes,

“engaging in economic espionage is something developing countries do. When you’re not yet generating a lot of intellectual property on your own, you imitate. These days, China is going to try to steal, and the West is going to try to stop it. But the tactic of using piracy to leapfrog ahead? That looks like an idea it stole from us.”

Continue reading

Software, Sharing, and Music

Here’s what was important this week…

Software is everywhere lately. My boyfriend asked me what I thought the next big website would be (after the success of Google, Myspace, Facebook, Twitter, etc.), and I realized it’s just as likely (if not more likely) to be a software application rather than a website. Paul Ford took some time to enshrine some works of software in a “software canon” — Microsoft Office, Photoshop, Pacman, the Unix operating system, and eMacs (which I’d never heard of until this essay came out).

Software has had a noticeable effect on our day to day lives (especially those with smartphones), but it’s also had a huge impact on music and the way it’s created, recorded, and produced. Fact Magazine went through 14 works of software that shaped modern music (electronic music started way earlier than I thought). One of those software applications is Auto-Tune, and the Sounding Out! blog happened to post about the history of Auto-Tune.

 

Continue reading

Journalism, Networks, and Grief

Here’s what was important this week….

Felix Salmon, a formers Reuters journalist, wrote a screed about why publishing news with the readers in mind is more valuable than breaking news.

As he puts it, “when journalists start caring about scoops and exclusives, that’s a clear sign that they’re publishing mainly for the benefit of other journalists, rather than for their readers. “

Even more clearly, and something that I can relate to easily, is the idea that:

“Readers come first, and all decent publications have their own readership: they shouldn’t be so meek as to assume that their readers will have invariably found the same news elsewhere, just because someone else’s version arrived a little earlier.”

When you spend most of your time on the Internet surrounded by, to borrow his phrase, media navel-gazers who lives on Twitter, everything starts to seem like unimportant, old news. But thankfully, when you talk to others outside of that arena, it is easy to remember that news that seems everywhere and overdone in one circle could be totally absent in another.

Continue reading

Handwritten Texts

I’m going to expand on some tweets of mine from earlier today about this blog post.

Cristina Vanko spent a full week responding to all texts sent to her with hand-lettered calligraphy notes, which she then photographed and sent back as her response. 

There is a vintage nostalgia element to practicing something of this nature, a throwback akin to the resurgent popularity of vinyl or of the constructed “aged” photo filters as examined extensively by Nathan Jurgenson, and one of her friends recognizes this with the comment “old schoo+new school”:

iphone screenshots capturing conversations between author and friends

old schoo+new school and wondering what took so long

The vintage nostalgia of writing out a text lends credence to the “digital detox” movement in a unique way. Cristina is disengaging from traditional digital practice, and yet still practicing the act and art of communication, but on her own, slower terms.

Continue reading