Home »

Write the Docs Newsletter – November 2018

Hi everyone! It’s Beth Aitman here, in my first issue as your newsletter editor. Hoping to continue Kelly O’Brien’s fine work bringing you news and interesting discussions from across the Write the Docs community.

I’m so pleased to be joining the team - I love the idea of this newsletter. It’s sometimes mentioned as a shame in Slack that we only have access to the most recent 10,000 messages (which is because, unfortunately, paid Slack is super expensive). Although some like the impermanence, it’s great to have the newsletter to counter it a little, keeping track of some of the wisdom that gets shared. In case you didn’t know, you can browse through all the issues of the newsletter on the Write the Docs website.

There’s plenty going on in the community at the moment, including gearing up for our second conference down under! Write the Docs Australia starts in Melbourne on 15th November, with a packed two-day schedule of talks, workshops and unconference sessions.

Looking further ahead, we have confirmed dates for Write the Docs Portland: 19th-21st May 2019. One to put in the diary!

So what have we all been talking about this month?

Promoting plain language

Recently, a new Slack member 🎉 used their first post in #general to ask about everyone’s experiences with encouraging plain language at work.

First off, most participants agreed that distributing a style guide isn’t enough, even with support from management. It can help to include justifications for the rules in your style guide - not only can it win colleagues over, it also helps people remember them. One documentarian suggested pairing every style guide rule with a second line explaining the rationale for it.

Another idea was to target a few issues at a time. For example, you might start by getting everyone on board with “using” rather than “utilizing”, then move on to eliminating passive voice.

If you’re the lone writer, you might have luck with transitioning to plain language without announcing it and addressing concerns as they come up.

More ideas for winning colleagues over included:

  • Developing internal content using plain language to demonstrate its usefulness.
  • Explaining that plain language improves translation accuracy and reduces translation costs, if that’s relevant to your content.

If you need help wrangling tech docs into plain language, try looking to your marketing. Marketing materials tend to use less technical language, and they might give you ideas for simpler ways to phrase things in your tech docs.

No matter what, adopting and implementing plain language seems to be a work in progress: almost everyone mentioned that they are looking for opportunities to improve.

How to hire a documentarian

How to hire is a topic of perennial interest. So fortunately, there’s a great new addition to the Write the Docs website: the Guide to Hiring and Getting Hired.

It came from the Writing Day at the Prague conference, when a group of documentarians got together to collect the questions that they use in interviews and the questions they like to ask when they’re being interviewed. All of this knowledge is now written up in the guide, aimed at helping out candidates and hiring managers alike.

Thanks to Kristy James for running the session and putting the guide together, and to everyone who contributed words and ideas!

Getting feedback from users

This month, there’s been a lot of discussion about gathering feedback from users on your documentation site. Here’s a quick summary of what we learned.

For starters, it’s worth remembering that your users’ attention is generally on the product they’re trying to use. They won’t tend to think about your docs as a whole, but rather about the product experience. So be careful asking questions about their experience of the documentation.

One option is a rating system on each page (a thumbs up or down, or a “Was this helpful? Yes/No”). These can tell you about trends, but many felt they rarely got actionable feedback from these systems. A thumbs down doesn’t tell you what the problem with the page was, so it’s hard to work out how to fix it. It can help a bit to ask for further information if you get a thumbs down.

To go further than that, you can ask more specific and relevant questions to prompt for the information you’re really looking for. Some options suggested were:

  • “What were you trying to do? Were you successful?” and if not, “Why not?”
  • “Where did you get stuck?”
  • “What did you want to learn? Did we help?” and if not, “What could be better?”
  • “Did you find what you were looking for? Did you understand it? Did it work?” If no to any, “What were you were trying to do?”

Upcoming community events

Write the Docs Newsletter – October 2018   Announcing Write the Docs Portland 2019 CFP