Home »

Write the Docs Newsletter – September 2022

Hey, everyone, the newsletter is back! We took one of our regular breaks, but now we’re back with exceptional insights from the Write the Docs community.

If you’d like to get more inspiration from the community, it’s your last chance to get tickets for the Prague conference. Ticket sales end on September 8. Then the conference starts September 11. We’ll certainly all have lots of new ideas to think about afterwards.

And if you have ideas of your own to share, there’s still (a little) time to propose a presentation for the Australia conference. For more details, see the Call for Proposals. The deadline for submissions is September 16. And you can join the conference to see all the amazing ideas on December 8–9.

And we still have the excellent thoughts from the past couple of months to share with you here. A reminder that if you see a conversation in Slack that seems relevant for the newsletter, tag it with the :suggest-for-newsletter: emoji. We’ll summarize the most interesting topics here (almost) every month.

Collecting helpful user feedback

Getting helpful user feedback is an eternal concern for documentarians. Is there a collection method that both encourages user participation and delivers categorizable data about docs quality and effectiveness? Open comment fields give users space to expand and offer details, but lengthy comments can be difficult to categorize for higher-level analysis.

One-click ratings mechanisms with limited options offer a low obstacle for users—think thumbs up/thumbs down icons or a range of smiley faces like HappyOrNot. The limited options are helpful for finding patterns in feedback and some documentation platforms even have such ratings tools built in. The drawback is that ratings scales often don’t include a way for users to provide details, so you don’t get any information about the reasons behind the user ratings. If you choose to collect ratings, take care to offer only a few options to keep the feedback meaningful.

Some have had good results with prefilled feedback options as a middle ground between open-ended text fields and limited one-click rating scales. For example, you might ask users to complete a sentence from a list of short answers, such as completing “This page is…” with options like “helpful,” “incomplete,” “confusing,” or “too long.” The prefilled answers provide more detailed information that’s still categorizable without burdening users. If desired, you can include options for sending detailed feedback or even creating tasks for doc team review.

When to use acronyms

Style guides such as the Microsoft Style Guide suggest spelling out acronyms and abbreviations at the first use, except when the short versions are well known. This led to the question of how do you know that an acronym is known well enough? Where do you draw the line?

People noted that, as with many questions about documentation, it depends on your audience and what they know. Some pointed to acronyms such as URL, HTTP, and API being better known than the spelled-out versions, especially among more technical audiences. They worried the long versions would actually be harder to understand. One person pointed to a threshold of 90% of users knowing the acronym as enough to use it without defining it.

Others worried relying on a rule about common knowledge would mean people would abbreviate too much. They’d assume their audience knew technical terms like they do. And your audience can always expand beyond your initial ideas, so you may have more nontechnical people reading than you might think.

Many people agreed that it’s better to err on the side of defining too many acronyms, rather than too few. You never know if someone will see the term for the first time in your docs. It can be good to use some acronyms to shorten text when they appear multiple times, but take care not to let your docs get too full of acronyms that they become incomprehensible.

Improving communication about what’s in releases

We recently had a discussion about how to keep communication in sync between engineering, product managers (PMs), and documentation. In particular, about making sure that documentarians know if the product is changing so they know what needs doing for a release.

The original poster hadn’t had much success asking engineering to keep them informed – often engineering would forget. So they were thinking of trying to improve this with better process, via PMs; surely PMs keep tabs on what’s changing in the product and are aware of what changes might need doc work?

The answer is, it depends, because how PMs work with engineering can vary hugely among organizations and even among teams. Some PMs are the main point of contact for what’s changing, and want to be kept in the loop. Others are focused on handling user requests and reviewing feature designs and aren’t really involved in launching, in which case engineering is a better source.

Several contributors agreed that working together more closely was the answer. Many tech writers get involved in longer-term planning meetings or even join in sprint meetings; this helps with understanding what’s coming up without introducing new processes or extra effort for other roles.

A lot of it does come down to building relationships. You can institute a process that’s meant to keep tech writing informed – but ignoring a checkbox isn’t so hard for your colleagues. Whereas if they know you, talk to you regularly, and understand the value your work brings, they’re much more likely to provide you with the information you need.

Is coding necessary to write good docs?

Do you need to know how to code to write good docs? Many individuals interested in the field have asked this question. Even seasoned tech writers ask and are unable to get a definite answer.

In short, no. To be a documentarian, you don’t need to code. However, the skill is valuable and may make you more employable. Knowing how to interpret code can also be useful if you come across API documentation or need to edit code comments at work.

If you think learning how to code will better your career prospects or help you stand out at work, websites such as freeCodeCamp can help you learn languages like JavaScript and Python. If coding seems out of reach, try learning fundamental computer science concepts and how development teams work within an organization. You may find it easier to communicate with engineers with just an understanding of the basics.

Ultimately, while coding isn’t necessary for the job, many tech writers can benefit from some experience to make writing about software simpler. But keep in mind that, whether or not you decide to code, tech writing requires more skills than simply writing, so specializing in a niche can help you in the long run.

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: The Atlantic points out that while striving for more diversity, individual people are mistakenly targeted as being “diverse” in themselves.

A medium read: “Professionalism is, by its provenance, a legacy of elites.” Business Insider explains professionalism bias.

A longer read: MIT Technology Review discusses the history of tech and its ongoing problem breaking away from being a straight white man’s world.

From our sponsor

This month’s newsletter is sponsored by Zoomin:

Enough with the stone-age publishing process! Learn how you can update product information from every source across your company and delivers personalized product answers wherever your users need them

Wanna know how Xandr designs customer-centric product content experiences? Read Success Story

SPONSOR

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

Virtual events coming up

Get Ready for the conference!   Conference highlights and thanks for attending!