Home »

Write the Docs Newsletter – October 2022

Hello once again to the wonderful Write the Docs community. While the weather may be getting cooler in my part of the world, I can always find something to warm my heart in this community.

Some of what makes the community great was on display last month at the Prague conference. If you weren’t able to see the talks as they were broadcast and join in the productive conversations, you can at least catch up on videos of all talks, including the lightning talks. And if you want a visual guide to each talk, you can find sketchnotes for each talk on Flickr. The talks represent a variety of perspectives and experiences so you’ll probably find something to inspire you.

If you’re like me, you might be so inspired you feel like you have to give something back to the community. One way you can help is by joining the teams that help keep the conferences and Slack group running smoothly. Take a look at the list of teams and decide what area fits you best. For example, if you’d like to contribute to the newsletter, reach out to me (Aaron Collier) on Slack. Or find something else that suits your skills. We also understand if you need to conserve your energy to care for yourself and those closest to you.

Whether you have the time and desire to contribute or not, we hope you’ll get something useful out of this month’s discussions.

Tactics for motivating docs contributions

If you rely on others to draft and review documentation, it makes sense to think about how to improve the process to make it more productive and encouraging for everyone. Docs contributions can drift toward repetitive reviews with never-ending questions and answers that eventually demotivate those whose help we need. Here are some ideas from the community to boost motivation for docs contributions.

  • Accommodate contributor preferences and working styles as much as possible. Some appreciate time-saving synchronous conversations and others prefer asynchronous back-and-forth. Start with a question like, “Would you prefer a call to go over this or is back-and-forth messaging better for you?”
  • Minimize the number of review cycles to prevent docs fatigue. For example, if you’re reviewing a draft, try to ask all of your questions at once rather than trickling them out over time. Offer a call to resolve any difficult or repetitive questions. Shorter review processes help make docs work feel quick and rewarding.
  • Communicate about the process. Tell contributors what you need now and what you may need later. For example, “After you post your draft, I’ll review it. I’ll need to ask some questions to make sure the doc is complete and accurate. How would you prefer to communicate about this doc and any questions? We can have a call or I can post comments for you to answer or something else.”
  • Manage your own expectations. When you’re trying to keep motivation high, it doesn’t pay to be too strict about style guide adherence. Try to get understandable, working documentation – you can complete stylistic editing later. Focus on collaboration instead of perfection and try to nurture a culture of docs ownership among contributors.

Estimating docs work

How do you measure the work that makes up a documentation task? This can help when you’re trying to communicate your workload, and it’s more useful to have a sense of ticket size than just your raw number of tickets.

There are tons of approaches to estimation and our community shared a few that work for them. Which approach is right for you depends on what you’re trying to get done. Do you need to be certain that you can deliver by a certain date? Or do you just want to give a sense of how much work your team is doing?

Our first option is T-shirt sizing:

  • XS: Less than 20 minutes – like fixing a typo.
  • S: Less than an hour – like rewriting a small amount of text or refactoring.
  • M: Half a day to a full day and takes some thought.
  • L: More than a day and involves research or getting context.
  • XL: New feature or product work. May require sync meetings, iteration, more work tracking.

If you have a strong sense of how much effort the work is up front, another approach is story points as essentially time estimates:

  • 1 point = up to 1 half day of work.
  • 2 points = 1 day.
  • 10 points = 1 week.
  • 20 points = 1 (2-week) sprint.

If you have this much certainty, this is great for helping you see if you’re over- or under-committed for a sprint. On the other end of the spectrum is an approach based around uncertainty (and the Fibonnaci sequence!). The bigger the number, the less sure you are about how much time it will take:

  • (1): Trivial, little thought required.
  • (2): Know exactly what needs to be done, just needs the time to implement.
  • (3): Know most of what needs to be done.
  • (5): Some things still need to be figured out, but the pieces are all there. No major unknowns.
  • (8): Lot of things to figure out. Some unknowns.
  • (???): Work that you can’t estimate, like research (it could last forever!). These usually need either breaking down or time-boxing.

Gerunds in headings

Gerunds, words formed with verbs but functioning as nouns like installing, creating, and configuring, have been considered a problem in headings in technical documentation. Arguments for resistance include the fact that gerunds introduce a lot of visual repetition, which hinders skimming and causes noise. Gerunds are also inconsistent with how people browse the internet. For example, people are more likely to search for “remove user account” than “removing user accounts”. Moreover, gerunds can be challenging to translate and localize since some languages do not have identical counterparts.

Despite the caution about -ing words, some people prefer them in headings since they are accustomed to them as a common standard. In addition, gerund advocates like to use them in tutorial-style content where the reader is active in completing a task. Others feel they add a friendly tone to the document that helps the reader feel like an active participant.

Depending on your specific situation, the disadvantages of using gerunds may exceed the benefits. Gerunds, for instance, can add vagueness to headlines, are not always reader-centric, are often time-insensitive, and can often be weak and use the passive voice. The takeaway here is that if the intent is to communicate a command plainly and not infer the process of action ambiguously, consider using imperatives. Additionally, consistency is key, whether you prefer imperatives for their directness or gerunds for their conversational tone.

If you want to learn more about gerunds in headings, check out Ann Wylie’s opinions or a discussion on Writing Stack Exchange for further suggestions on forms for verb tenses in document titles.

What we’re reading and watching

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: WELCOA offers a look at belonging and how it helps make business better.

A short video: In Don’t take the exit on people, Justin Jones-Fosu focuses on taking the time to learn about other people in order to manage bias.

A book recommendation: Just Work by Kim Scott continues the topic of Radical Candor but specifically addresses the challenges it presents to underrepresented groups.

Virtual events coming up

Announcing speakers and talks   Announcing Full Schedule