Home »

Write the Docs Newsletter – April 2021¶

Hello everybody! It’s Beth and the team, here with the Write the Docs newsletter for April.

No big announcements for you this month, but things are ticking along nicely. Portland’s coming up in a few weeks, and tickets are still available - they’ll be on sale until about a week before the conference. If you’re undecided, check out the full schedule.

On to our stories from the WTD Slack. We’ve got plenty for you this month, including how to counter the idea that “nobody reads the docs”, the pros and cons of publishing a reading time, and a new feature from the #bipoc channel on what they’ve been reading recently!

Addressing the user as “you”¶

This month’s discussions included the question of whether it’s OK to directly address the reader in the second person (as “you”) in technical documentation.

Sometimes “you” isn’t quite right. For example, in API docs, it may be more accurate to talk about what “the application” does rather than the actions a user might take. Or you may not need to address the user at all, for example when you’re describing default settings: “The default setting for $Property is 10.” In other cases, your company style guidelines or docs stakeholders’ opinions may discourage or even prohibit the second person.

However, most people said they use “you” without reservation in documentation. Using “you” can make sentences easier to read, impart a more conversational tone, and help avoid passive voice. And it’s not without institutional support: Microsoft recommends using “you” in documentation, as do many other companies – for a list of many examples, see Daniel D. Beck’s The second person is OK in developer documentation (but don’t take my word for it).

Dealing with the myth that people don’t read docs¶

We’ve all heard it - the idea that documentation doesn’t really matter, because nobody reads it anyway. And if you’re reading this newsletter, you’ve probably got a strong feeling that it isn’t true. But how do you refute the idea when people bring it up?

The Write the Docs Slack community had some great ideas on this, ranging from the serious to the lighthearted. On the immediately useful end, you can point people to docs site analytics, or to community surveys (such as those run by GitHub or DigitalOcean). These give you immediate data to show the myth isn’t true. Asking colleauges which user studies they have been carrying out that suggests that people don’t read the docs will at least give you time to think of another answer. You can also highlight that people ‘read docs when they need to, not for fun’, or indeed mention the value of clarification inherent in the docs process even if those docs don’t get read.

On the less serious side, you can try deleting the docs and letting the person asking the question field the support tickets. Or “just” make the product good enough that it doesn’t need docs.

And finally, as ever, it always depends. How much users actually read and use the docs will depend on what kind of product you have, and what kind of docs you have, among other factors.

Reading times on articles¶

What do you think of having an estimated reading time at the top of an article? In a poll in #general, 48 of 75 respondents said they ignore them: they assume the estimate is wrong or it just doesn’t affect whether they read the article. Seventeen respondents said these estimates are helpful in deciding whether to read the article now or later. The other 10 respondents said they were less inclined to read articles with estimated reading times, either because they seem too long or too short.

Aside from the poll, the resulting discussion turned up some interesting points about these reading times. For example, the estimates are unlikely to be accurate, due to different reading speeds, different perspectives about what is “long” or “short,” and how much time people have free when they encounter the article. Some content calls for close reading and other content is more skimmable, and that assessment also differs from person to person.

Why have an estimated reading time at all? One answer is time management: readers can read shorter articles right away and save longer articles for when they have more free time. Another could be better reader engagement, as argued by Michael Marchese in Why it’s important to add an estimated reading time. Checking that would be a good topic for A/B testing.

As for how anyone arrives at these reading time estimates, check out Nicholas Gryman’s reading-time project on GitHub. The Michael Marchese post also includes a basic formula that uses words per minute.

Improving your editing¶

Plenty of us do more rewriting than writing. Some are full or part-time editors; sometimes it makes sense for SMEs draft the content, and then a specialist writer fixes it up; some of us mostly work with existing material that needs restructuring or bringing up to date. So how do you improve your editing?

Several documentarians agreed that the most important way to improve your editing is to edit more. Don’t just read books or take training courses.

That said, it’s still interesting to read tips from great editors! Some recommendations: On Writing Well by Zinsser, Bryson’s Dictionary for Writers and Editors by Bill Bryson, On Writing by Stephen King; The Elements of Eloquence by Mark Forsyth; The Sense of Style by Steven Pinker; The Oxford Style Manual by OUP; First You Write a Sentence by Joe Moran. One documentarian got huge value from the Chartered Institute for Editing and Proofreading’s resources and forums.

Another tip was to understand why the “rules” are there. Digging into linguistics and anthropology can help you figure out if a rule is actually helpful or not. And a grammar reference like The Gregg Reference Manual can be helpful day-to-day.

Finally, editing challenges are sometimes not about words but relationships. Some authors have very set ideas about writing! So communication and conflict resolution training can be useful. If you work repeatedly with the same people, it’s worth learning their quirks, over time giving feedback on some common problems they could avoid. Style guides can also help lower the temperature of a disgreement: sometimes it’s productive to explain your reasoning, but other times appeals to authority can save a lot of energy!

What we’re reading/listening to/watching¶

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Join us in the #bipoc Slack channel!

For a short read, check out: Words Matter: Finally, Tech Looks at Removing Exclusionary Language by Jennifer Riggins, June 2020. It discusses the tech industry’s look at the language it uses, because words do matter.

If you have a little more time, you can listen to: BLM, inclusivity and techcomm from The Cherryleaf Podcast discusses what technical communicators can do at work and elsewhere. It’s an older episode, but still relevant in today’s landscape. Be sure to click view more for the links discussed in the episode.

If you can invest more than an hour, there’s: We Need To Talk About Anti-Asian Hate by The Try Guys. This video talks about everything from the history of Asian immigration to the United States, to the current wave of hate crimes being committed, to what you can do to help. It’s divided into chapters, which makes viewing it easier in smaller chunks.