Write the Docs Newsletter – June 2020

Hey all - it’s Beth and the newsletter team here.

It feels like more and more often that I write to you while the backdrop is bleak, and it would be impossible to not talk about the ongoing protests around the world. Inclusion is at the core of Write the Docs; we are distraught by the suffering, oppression and systemic racism the Black community faces every day. This is much better said in our statement of support, but in particular I wanted to mention that we are matching donations, up to a total of $1,500, to non-profits working to support the Black community. See the blog post for how to tell us about your donation so that we can match it.

As May has drawn to a close, we’d usually be talking all about the Portland conference, but of course no such news this year. But to have something to look forward to: tickets to the virtual Portland conference are now on sale. We’re still finalising exactly how everything will work, but the plan is to stay as close to the usual spirit of our events as possible - so including Writing Day, unconference sessions, and a virtual hallway track. Check out the list of talks, and buy your tickets here.

And if you’re in a time zone closer to UTC like me, keep your eyes peeled - we’ll be announcing dates for virtual Prague sometime soon.

With that, let’s see what the community has been talking about this month.

Types of docs and how to use them

Back in 2017, Daniele Procida gave an often cited talk, The four kinds of documentation, and why you need to understand what they are, written up into this article. Our community spent some time discussing the details of how to apply Danielel’s type distinctions, with some help from Daniele himself. As a refresher, the four types are:

  • Tutorials, or learning-oriented docs
  • How-to guides, or problem-solving docs
  • Explanations, or understanding-oriented docs
  • Reference, or information-oriented docs

Here’s how the conversation built on these types:

  • Regardless of the type of doc, make sure to provide context to orient the user. Do they need to learn more before they read? What level of expertise is the doc aimed at?
  • Other terms used to refer to the same types are “concept” (for explanations), and “procedure” – which could cover both how-tos and tutorials, because all share a step-by-step approach. But a more nuanced distinction emerged. Tutorials can be thought of as step by step how-tos, but involving larger tasks or a broader grasp of how things work. How-to docs are smaller, and show how to accomplish only a single task.
  • Some folks thought of tutorials as the place for users to get started learning how to make your product work, whereas others saw them as entry points for anyone at any level of expertise.
  • But all agreed with Daniele’s recommendation not to mix types - and agreed that no matter how carefully you structure your doc content, users will eventually do their own thing with it.

Common words and how to identify them

When we decide which words to use in our documentation, it’s important to determine how common a word is. Common words are easier to understand and make your documentation more accessible to a wider audience. Picking the more common word can also be a handy way to settle a word choice disagreement - as enjoyable as the debate may be!

In addition to researching the words you use, you can user test them. If your (representative) test users don’t know what the words in a document mean, or have difficulty understanding the procedure because of the words used, this can help you confirm that the words are uncommon, or at least not right for your audience.

Here are some tools to help you tell if a word is common or uncommon:

Obvious things and whether to document them

Recently, a discussion on Slack was sparked on the topic of whether or not you should document the “obvious”.

Those against documenting the obvious gave the example of uncomplicated UI procedures like deleting an object: if it’s something you’d expect users of almost any software to be familiar with, you could expect your audience to know it already. Plus, the downsides of being explicit include describing how to fill in every field in detail, or multi-step procedures for something the UI guides you through. More detail like this can make docs feel very long and cluttered, and make it hard for readers to find the bit that’s important to them. And explaining things in too much depth can come across as condescending.

In favour of documenting the obvious: what’s obvious to you isn’t necessarily obvious to others. Besides, those who already know something can skip over it. This discussion provides a reminder of how important it is to know your user base - what is “obvious and familiar” depends on your background, exposure, and contexts. At minimum, make sure you know what your assumptions are: if your assumptions are explicit, you can make deliberate choices on what to leave in and out, based on the intended audience.

Ultimately, be guided by what your specific audience needs to know to achieve their goals. That’s what belongs in documentation.

From our sponsor: Open Source Curious? Learn (and earn) with Google’s Season of Docs!

This month’s newsletter is sponsored by Season of Docs:

"Season of Docs is a program from the Google Open Source Program Office that connects experienced technical writers with open source projects needing better docs. Writers receive a stipend and mentorship! Applications due July 9!"

Season of Docs

Interested in sponsoring the newsletter? Take a look at our sponsorship prospectus.

Job posts

To apply for these jobs and more, visit the Write the Docs job board.

Virtual events coming up