Home »

Write the Docs Newsletter – May 2023

Aloha, documentarians! I hope any showers you may have experienced in April are paying off in flowers. There’s lots blossoming within Write the Docs.

The main thing going on this week is the Portland conference. Wishing all of you who will make it to Portand safe travels, and if you can’t make it there, you can follow along with the main talks through the livestream.

If you get inspired, there’s still time this month to submit a talk for the Atlantic virtual conference. Check out the Call for Proposals and submit your proposal by 15 May.

And after that you can look forward to our third conference of the year, in Australia. Check out the announcement for the dates and start planning for December.

Away from the conferences and back to this newsletter, I’d like to extend thanks from Write the Docs to Heather Zoppetti. For a long time, every month she took brought you discussions and things to read or listen to from the #bipoc channel. We appreciate the hard work that went into this, but it’s a difficult burden to carry alone. If you’d like to continue the conversation, join in the #bipoc channel.

I hope you have pleasant and insightful conversations, whether in Slack, at the conference, or elsewhere in the world of documentation.

The importance of docs… in 30 minutes

If your company gave you 30 minutes to give a presentation about why documentation is important, what would you say? The “Docs or it didn’t happen!” motto can be a useful starting point because it’s catchy and memorable. Another idea is to start by asking the audience to remember a time when they were frustrated by a product’s instructions—and to think about whether they would give that product a good or bad review.

Focus your talk on the business value that documentation provides, such as improving product adoption, deflecting support cases, and increasing the value of existing engineering work. If possible, include specific examples that demonstrate how documentation solved a question or problem or led to a successful business outcome. Talk about the benefits of good documentation rather than its characteristics (like clarity and conciseness).

You might also explain the kinds of information that you typically need from subject matter experts and product managers and how it helps you craft good documentation. This reminds the audience that you’re allies with the same goal: making sure your customers can use your product to solve their problems.

For a few more thoughts on the subject with a side of laconic wit, check out the blog post Proving and defending the value of technical writing, again by documentarian Bob Watson.

Getting past tech writer’s block

One recent Slack discussion started with questions about transitioning to a technical writing career. But many of the suggestions seem appropriate to addressing the blank page syndrome (the fear of starting to write) that some documentarians experience.

People also brought up imposter syndrome (doubting your ability to document well) and suggested that this thought could make a transition harder.

So, here are some suggestions that might break through the blank page syndrome and make you feel better about being a documentarian:

  • Just write… anything. (Suggestions included non-work writing such as a personal journal or a blog.)
  • Find something to rewrite. (Think about the improvements that you make.)
  • Identify different types of writing (such as procedures, tutorials, or overviews). If there is one type that’s easier for you to do, start with that type of document.
  • Make outlines… or mind maps… or just list words that may be relevant.
  • Specifically write a first, rough draft to get some words down without expecting that it will be good work. (One person suggested calling this a “zero” draft, which is not even a rough draft.)
  • If your product is software, read through existing documentation or tinker with the software.
  • Browse documentation for similar products. Notice what you find interesting, helpful, or distracting. Try adapting what you see for your product.

Several people reminded the group that technical writing is NOT creative writing. So being able to communicate clearly to someone who knows nothing is more important than being creative. If you follow basic documentation guidelines, you might get some words written AND decide that you aren’t an imposter after all.

How to describe career progression

If you ever find yourself having to write job descriptions for documentarian roles, you might find it challenging to define the role’s level—such as junior, senior, or principal. The problem isn’t so much the hierarchy of job levels as what exactly the role levels mean. For example, some might think juniors strive to do things, seniors demonstrate the ability to do things, and principals are role models in how they do things. But then you might be questioning what those things are.

One way to put it plainly is:

  • Juniors contribute to doing things with assistance and review from others.
  • Seniors do things independently.
  • Principals do things independently and refine and develop how things get done.

You can define career levels for junior, senior, and principals in many ways. Regardless of the definition, the levels reflect how much supervision people need and their impact radius. Usually, juniors have a smaller impact as compared to a principal, who looks to make an impact across a product or company by mentoring others, finding global solutions, and guiding a team to use more efficient and effective processes and procedures. When making comparisons, higher levels have more influence on how things get done.

It’s also important to know that career levels differ not just by workplace but also by country. Some people aren’t familiar with certain U.S. job role levels, especially principal as the most senior. In these cases and others where job roles seem ambiguous, it’s best to define them well, securing them within the organization’s unique context and clearly defining “the thing.”

What to do after surviving layoffs

Many tech companies are going through layoffs at the moment and it’s not an easy thing to live through—whether you’ve been laid off or even if you make it through. This month, a community member asked for advice with handling survivor’s guilt after a round of layoffs. Here’s what folks on Slack thought.

First up, feeling uneasy or guilty is a normal reaction, as is worry that this round won’t be the last. Some companies recognize this and give folks a bit of a pause to process, but some don’t. It’s also reasonable to feel glad about still having your own job, even if others don’t.

One thing you can do is help out those who were laid off. Checking in on former colleagues, seeing how they’re feeling, and checking if they would appreciate written recommendations or hearing about good job openings: all of these are kind actions to take.

Lastly, some folks recommended spending time on simpler work: you can lose yourself in quick wins or more routine work that takes less brainpower. It can be a helpful way to pass the time while you are processing.

Events coming up

Welcome to Write the Docs Portland 2023   Write the Docs Community Board Quarterly Update Q2-2023