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!

My impressions from the 2017 Bay Area Book Festival

For the second year in a row I attended the Bay Area Book Festival. A collection of authors, publishers, readers, and other bookish sorts also show up for the weekend in Berkeley. This year, like last year, I discovered some great sessions that led me to think about things from a new perspective and that I might not otherwise have learned about.

One great thing about the book festival is that, true to its slogan, it connects readers and writers. Much like the podcast Song Exploder, the sessions caused me to think far more about the process behind creating the things I love than I might have otherwise.

Something that struck me and my friend, however, is how few of the attendees were young. There are a lot of attendees (of sessions, especially) that seem to be retired, quite a few middle-aged people, and in the YA-fiction sessions I attended, a good number of children and their parents. In fact, much of the festival seemed designed to be family friendly.

However, in a reflection of publishing at large (perhaps) the festival neglects the population that is most clearly present in Berkeley and the Bay Area to me—the ~ * millennials *~ that attend the university and work in tech and other industries all around the bay. I saw a few other people in their mid-twenties and mid-thirties, but not nearly as many as I’d hope to see. No one that I talked to in that age range (save my friend) knew about the festival that weekend, and I saw almost no marketing for it aside from the emails from the organizers (thanks to signing up for the email list last year) in the social media sites and feeds that I follow. Hopefully in future years this will change.

I also struggled to determine who the actual target audience of the festival was based on the sessions I attended and the booths I witnessed wandering around (I’m not much of an actual booth-visitor). The fest again, advertises itself as connecting readers with writers, but it seemed to be connecting writers with other writers just as often. Whether on panel discussions or through writer-oriented booths in the park, that was a very present and understandable theme. I’m not sure it matters that the target of the festival is so broad, and perhaps it might flourish even more if it were more explicitly targeted to this wider audience. But again, perhaps not.

I attended two sessions each day of the festival, and here are my impressions of each of them.

Saturday

The first session I attended on Saturday was called Worlds We Create: Young Adult Fantasy Writers on Creating Alternate Realities and Memorable Characters. It’s only in the last year or so that I started realizing that I do read fantasy and sci-fi novels, and while I didn’t seek them out when I was younger (sorry, Tamora Pierce and Phillip Pullman), I always enjoyed historical fiction and fairy tale retellings. This session was explicitly about how fantasy writers go about creating the worlds in their novels. The moderator had some great questions, they asked about how authors develop characters to reflect the world they inhabit, whether the story or the characters or the world come first, and more.

They discussed using “sensitivity readers,” a concept I hadn’t heard of before this panel, who you can hire to provide feedback and criticism about the way that you’ve told the story of a character with experiences that you haven’t had directly. One of the authors, who set her latest book in turn of the century New York City, spoke of the balance of being sensitive to certain life experiences and having to confront discrimination with the focus of blowing it up in the book.

Needless to say, I’ll be thinking a lot more about the quality of worldbuilding after this panel. I was in the midst of reading a series that was set in a world that took awhile for me to understand, and seemed to use a glossary to attempt to offload some of the worldbuilding heavy lifting, yet the story and the characters were fairly well-developed enough for me to appreciate it and continue following through. The balance of world-building time and story-telling time was also covered in the panel, with one of the authors mentioning that she’ll use worldbuilding as a way to get started writing a new book if she’s struggling with how to start.

The second session I attended on Saturday was rather different from the YA fiction panel. This session featured Masha Gessen in conversation with Orville Schell on Truth, Lies and Totalitarianism in Russia and the U.S.. This session featured quite a few great moments. My friend pointed out that she hadn’t before heard someone speak with such attention to the precision of their language, yet that is exactly how Gessen spoke. She was very precise when agreeing or disagreeing with Schell, and didn’t mince words.

Some paraphrases of what she said in the session, along with my own characterizations about what she said, follow.

Totalitarianism succeeds through destruction… not durability of the presence of totalitarianism or genetic makeup or expectations but of the absence of shared understanding and society and other things that help you move forward in the face of it.

She took care to distinguish her perspective from that of Schell’s. He asked a question about whether totalitarianism or autocracy persisted in some countries due to the genetic makeup of people or due to a durability of the people, and she disagreed, though recognized that they agreed on the state but not the cause of the state. The absence of certain things, rather than the presence of something, is what is helping totalitarianism succeed and persist in these nations.

We’ve constructed a story about what happened in post-soviet states but not what happened in the west… democracy isn’t a state achieved by a country but a spectrum (becoming more or less democratic)

I really appreciated that she mentioned this. As someone who studied post-soviet states in college, I am quite familiar with the stories constructed there, but I hadn’t considered this perspective until she mentioned it. In my recent travels and events in the United States, it’s become clear that the Western states didn’t pay much attention to developing an identity that didn’t position other states as enemies and actively maintaining democracy.

Gessen also mentioned, perhaps in response to an audience question, why Trump admired Putin so much. In response to that, she referenced Tim Snyder in the NYRB, who wrote “Putin is the person that Trump plays on TV.” Expanding on that point, she continued that “Trump talks of power, off the charts popularity, and control… but doesn’t really understand where that comes from.” And where that comes from is autocracy. They also discussed her own article in the NYRB about autocracy.

Also discussed was the differing perspectives of politicians, businessmen, and others in an autocratic state compared with a democratic state.

There’s this belief from Russian politicians, journalists, businessmen that everything can be bought or is for sale or is transactional… a few years ago that didn’t fly here but that’s changing here… apparent struggle to understand non-transactional motives in authoritarian societies and possible explanation for a lack of understanding of civil society… If public service and nonprofit motives are questioned or not understood then democracy is challenged

Schell also brought up countries that don’t deal with history in an honest way (like many totalitarian states, Russia or China especially have quite censored and limited views of their own past), she spoke of WWII as being a touchstone in Soviet history in rewriting the past, but also continued to discuss whether a society can move forward with a distorted view of the past.

All societies have distorted views of the past…that’s trauma that societies have to deal with. Estonia for example has done a good job with this: “we trust one another, we were under occupation, and we’re going to rebuild based on that trust.”

Germany had the advantage of short period of time and everyone could remember pre-totalitarianism and talk about perpetrators, bystanders, and victims…. but it’s totally muddled in the Soviet Union; people were both perpetrators and victims and no one was a bystander.

How do you take responsibility for your own past if you messed it up? Whitewash the history…

One of the things that she mentioned as being most challenging for rebuilding in (or after) a totalitarian or autocratic state was imagination.

How do you rebuild when you can’t imagine a future or a past…and sometimes you can’t imagine the present because it’s so awful that you can’t fathom it…you reach for the past and confuse lack of imagination with understanding

When asked about her hopes for Russia in the future, she was blunt. “Russia is hopeless, scorched earth.” She did expand in response to a follow-up question to discuss the small-scale successes of some friends of hers in starting focused community organizations, but acknowledged that people seeking to make change on a small scale, while inspiring, is a way of admitting defeat. After you start focusing almost exclusively on small-scale change, you’re no longer trying or dreaming of making those changes on a large scale.

Sunday

Sunday I slept in, so I skipped an earlier morning session I considered attending so again attended two sessions.

First I attended another YA fiction session, Reality Bites: Fiction About Teens’ Real Lives, which was really great. Another panel discussion, the authors discussed what they do when they write most of a book and realize it isn’t working, sometimes all you can do is “upcycle” some of the scenes into other books. The moderator also asked about recurring themes and iconography, and while one author mentioned trees (she writes largely thrillers that tend to involve the woods), another author mentioned that she often writes about the sky, likely because it represents us against the vastness.

Most relevant of all, I thought, was the discussion on how writing novels teaches you to be compassionate about multiple points of view. Kim Culbertson especially made some great points about this. Sometimes a character has to do something differently than the way you would. She mentioned that “Lots of people are uncomfortable when they hold themselves up to another person and the edges don’t match.” But she likes to challenge that in a way, to help people get to the understanding and consideration that other people are different from you and that may seem strange but it’s actually awesome, and we need to recognize that!

 

 

The second panel I attended was about immigration and identity, Living in Two Worlds: Crossing Borders and Identities to Create Home. The moderator asked each author in turn to speak about their book which led to a great focused discussion on the themes in each one.

First, Laleh Khadivi discussed her book and the challenge about writing about two worlds, especially that “one world is never going to believe the other world.”

Next, Lesley Nneka Arimah discussed her book of short stories. She mentioned that she included Facebook in one of her stories because she was tired of reading stories set in contemporary Africa that didn’t mention social media. She underscored that while traditional infrastructure in Nigeria and other countries may be lacking, everyone has a cell phone and electronic communication is crucial to how they live their lives. It seemed out of touch not to acknowledge that reality of life in her fiction.

 

Carolina de Robertis spoke next about her novel, but my favorite quote by her came from the Q&A after the moderated panel concluded, which was that “Culture is not static; we can shift culture and push it open with the narratives that we live and write.”

Pajtim Statovci spoke last about his novel, and addressing the fact that living through the trauma of immigration, especially as a refugee, doesn’t automatically make you stronger.

Sometimes our negative experiences don’t make us stronger. Sometimes they make us weaker and sad and pathetic.

That resonated with me, because it’s easy to look at those who have survived something traumatic and assign strength to them merely because they survived. But that isn’t always the case. This thread resonated with the other books on the panel as well, because the main character in Khadivi’s book is an immigrant who radicalizes after immigration. Lesley Nneka Arimah mentioned about wanting to write about flawed characters as well, in the vein that we often think of ourselves as better than we are, so she wanted to write about characters that do the wrong thing in service of finding their own truth.

Overall impressions

The festival was worth my time to attend, and spend time thinking and talking about books with and around other book-minded people. I look forward to the next year’s book festival and the sessions! It’s always easy to attend when it’s convenient to get to and the weather is beautiful. Now I’m inspired to tackle even more of the books on my shelves…

 

#tweetthedocs: Use Twitter to meet your users where they are

As a tech writer, it’s hard to tell how users get to your docs at all. They might be clicking on in-product help links, searching the web, or getting sent links from support. But you can get proactive about it too. Help users of your product get their questions answered by meeting them where they are—on social media sites like Twitter. You may already rely on marketing, sales, support, and search engines to bring users to your documentation, but social media is a direct option. You can tweet about anything from general topics that answer common user questions to drier topics that are important for people to know. Read on to learn how!

Continue reading