Home »

Write the Docs Newsletter – June 2022¶

Hi from your new newsletter editor, Aaron Collier. I’m taking over as editor this month from Beth Aitman and hoping to continue the doses of news and general awesomeness she and the other newsletter volunteers having been regularly bringing to your inboxes.

I certainly have learned a lot from her already on how to make a newsletter useful and interesting. But it’s also important to recognize that the heart of the newsletter comes from you, the Write the Docs community. I had a conversation in Slack recently with a long-standing member who didn’t realize they could suggest stories to be included.

So as I start this journey, I’d like to (re-)invite you to come with me. If you see a conversation in Slack you think would be great for the newsletter, tag it with the :suggest-for-newsletter: emoji. We’ll round up the most interesting and thought-provoking ideas and bring them to you.

The past month was full of goodness outside the newsletter as we wrapped up the Portland conference. Those who were there talked a lot about how great all the talks and unconference sessions were. For those of us who couldn’t make it, check out the videos of all the talks on YouTube to at least see the talks.

Looking to the future, the Call for Proposals for the Prague conference is open until the end of the month. So don’t hesitate to submit your idea.

But enough from me. Let’s get to what’s been on your minds this month.

Whether to say “please”¶

In a recent discussion, the WTD community was trying to figure out: does the magic word, please, have a place in how-to documentation and instructions?

Style guides (like Google’s) usually advise against it for a simple reason: conciseness. “Please” doesn’t add any information; an instruction remains the same instruction, with or without please. So going by the principle of removing unnecessary words, pleasantries should be removed.

But it’s not quite as simple as that because “please” does change the meaning, making a phrase into a request that could be optional. For something that’s required, leaving out “please” may be the safest bet.

It’s common to see “please” used when the writer is trying to be friendly or polite. Direct instructions can come across as rude to some people or in some cultures. And when the user is disgruntled, “please” can be softening – appropriate when you’re asking the user to do something annoying or when it’s your software’s fault (“If the application crashes, please send us the following troubleshooting information…”). This is particularly relevant when you’re writing error messages. However, the counter-argument is that the politest thing to do is not to waste the user’s time. You can be polite by being clear and concise, rather than by starting every instruction with please.

If what is considered polite varies across cultures, translation may have an impact too. The community was pretty uncertain about this one though. On the one hand, it might be best to leave your translator to decide how polite the phrasing should be. On the other, many translations are done word-for-word, so you most likely will need to make a judgement call after all.

Edge cases and when (and where!) to document them¶

A question about the extent to which we should cover edge cases in UI text produced yet another thoughtful and informative discussion. In response to questions such as whether to provide or avoid UI text for edge cases, what constitutes a “major” edge case, and what full coverage of all edge cases might look like, our invincible community produced the following wisdom:

Maybe features specifically for edge cases would be a better place than a generic part of the UI.
One rule of thumb is if a case applies to fewer than 20–25% of users, don’t worry about it in the UI. This is especially true because there’s rarely room for it. But one person suggested that, depending on the larger context, you might want to lower that threshold to 5%.
Other strategies could include different product design, including progressive disclosure, depending on how users interact with your application.
Might risk mitigation be another meaningful variable in determining how and how much to explain an edge case? For example, even if only one major customer occasionally experiences a major disruption only some of the time, if the impact to the business is great, maybe it should be explained in either the UI or the documentation.
The documentation might be the best place for exhaustive explanations of edge cases – especially for complex security scenarios.

Estimating work¶

Estimating the time it will take to complete a task or assigning story points for work can be challenging, especially if you haven’t done it in a long time. If you find yourself in this situation, there are a few ways to help you correctly approximate the hours or effort needed.

To start, you might consider eight hours to be equal to about one page of work. This calculation can be useful whether you use Flare or other authoring software, but it is often tricky to determine how many pages you have to begin with. Check out a helpful guide on estimating writing projects for more tips.

Another option for evaluating work is to assign story points where one point equals half a day of work, two points equals one day, and ten points equal a business week. Though subjective assumptions about the degree of effort for a unit of work may appear odd, it is essential to keep in mind that story points are not time-based and therefore differ from hours.

Instead of focusing on hours, you might think of story points as a more reliable indicator of effort that helps in the division of work. Finally, remember that story points can be assigned based on factors other than just effort, such as complexity and uncertainty.

When used correctly during team planning, story points can give quick approximations, improve project forecasts, and even provide managers with actual statistics during hiring conversations.

What we’re reading¶

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

A short read: Talent Management describes why many DEI efforts fall flat and how belonging may be the key.

A medium read: Want to be more supportive of underrepresented groups but aren’t sure how? The Muse offers seven examples of how to become an ally in the workplace.

A longer read: Now a national holiday in the United States, June 19th is Juneteenth. Want to learn more about it? Oprah explains the history of Juneteenth.