Home »

Write the Docs Newsletter – March 2022¶

Hello, everyone! Spring is here and so is the March edition of the newsletter.

For WTD it’s been a fairly quiet month, with the Portland CFP now closed but ticket sales still open. I don’t have any conference or community updates for you at the moment, so we’ll just jump straight in to our articles, bringing you the best of the last month on Slack:

Domain knowledge: Breadth or depth?¶

Technical writers come to the job with a huge range of experience and skills, as the conversations in our WTD Slack channels attest daily. When it comes to getting the job done and the product properly documented, what extent of domain-specific expertise is required? Does it take more depth of knowledge to create documentation, or does a wider but more shallow understanding suffice? Most people thought that wide is more valuable than deep when it comes to domain expertise. For one, it’s unrealistic to expect anyone to know everything about an entire product or technology. Even individual engineers are unlikely to have deep knowledge of every element of the software they develop. Technical writers can be more effective with broader knowledge of the purposes of different pieces of the product or technology - and crucially, how they all fit together. Broader knowledge helps documentarians maintain the high-level view that’s vital for many technical writing tasks, like designing the information architecture for presenting detailed product information. Some pointed out that depth of knowledge has its place too, expressed in the saying “You can’t document what you don’t understand”. In this approach, technical writers should know the same things a typical customer needs to know to use a product or technology. In cases where customers need in-depth knowledge, the writer does too. If customers need to customize code examples to use a product, the technical writer should understand the code examples and the customization use cases. Still, it’s more important for technical writers to know how to prepare documentation than every particular of their subject. Rather than knowing how to make API requests in several programming languages, for example, technical writers should know how to use Postman (or a similar tool) to configure example API requests in any supported language. From this perspective, “a little more than just enough” is the optimal balance of domain expertise for technical writers.

Automation dreams - and realities¶

A question asking which things you’d most like to automate about docs produced a plethora of wish lists and practical implementations. Here’s the list of tasks our community is ready to hand off to our robot overlords, small or mighty:

Screenshots and changes to UI text.
Comprehensive and accurate lists of which features are available in which version of the product.
Release notes! This can be quite feasible, if you generate them from issues or pull requests.
Terminology checks (“linter type of things” as one contributor expansively put it), broken link checkers, and more text and formatting checks.
Copying tables from one format into another (notably to Markdown or HTML).
Docs builds and deployments (not everyone works with CI/CD!).
Slackbots to create and even help manage docs issues and reviews directly from Slack conversations. A couple of folks use these, and one person offered an example from the UK’s Government Digital Services

Lots of ideas here - the next step is to go forth and automate!

The contrarian view: reasons to use “utilize”¶

It’s a technical writing commonplace to prefer shorter, simpler words. As George Orwell put it, “Never use a long word where a short one will do”. On this basis, “utilize” is a common target for replacement.

But is there ever a time when you should use “utilize”, instead of replacing it with a less pretentious substitute? Of course there is.

One reason for using the word is to avoid semantic satiation in a sentence - when “use” is too close to other words like user, end-users, or the phrase “use process A”. Another example when utilize might be the best choice is if precision is warranted — such as when describing something’s capacity, or the quantity of a resource being used. An example of this would be: “When CPU utilization exceeds 75%, use a load balancer”. Here, utilization — as in the practical or effective use of something — makes sense because it fits the sentence’s professional and technical context.

But those are exceptions to a general rule. Both Google’s and Microsoft’s style guides recommend avoiding the word unless it’s really needed, instead recommending using basic verbs without modifiers. It’s also important to remember that the audience influences word choice, so choose the language they’re accustomed to.

When it comes to utilize, it’s safe to say that it’s preferable to stick with use. However, if “use” isn’t precise enough and you need a word that emphasizes something’s technical connotation, then use utilize.

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 article from the Washington Post (paywalled), talks about the origins of the word “woke” and how it’s been transformed into something else.

For a medium length article, CNBC offers a discussion about The difference between DEI and anti-racism at work, according to the diversity chief of Twilio.

In a longer article from SFGATE, learn about Ketanji Brown Jackson, the first Black woman nominated to the United States Supreme Court.