Write the Docs Newsletter – May 2026

2026-05-05T00:00:00+00:00

Hello to all of my fellow documentation lovers out there. May is blossoming all around me, and I hope it is for you and that you have some time to stop and enjoy the beauty you can find.

I’m writing this as the Portland conference is happening, so I am full of vicarious inspiration (and perhaps a little envy). If you’re also feeling some of that, you’re in luck, because there are three more events this year. First up is Write the Docs Kenya, which will happen on 8 August. Then in September, there’s the Berlin conference with tickets for sale. And if you feel just a little bit more of a spark, the call for papers for Berlin was just announced. Turn your idea, no matter how big or small it may seem, into inspiration for others. And keep your eyes out for Write the Docs Melbourne, which is planned for 3–4 December.

You can get inspired by documentarians from across the world not only through the conferences, but also through our annual salary survey. Check out the survey results. You’ll find insight from people from 48 different countries, and hopefully it’s insight you can use the next time you’re having a discussion about salary.

For inspiration closer to home (likely right in your inbox as you read this), we have articles this month on what makes documentation beautiful, whether to use words like “recommend” in docs, and whether “technical writer” is an outdated job title.

Some kind of beautiful

A question landed in Slack this month: “What makes documentation beautiful?” The responses were like a series of love letters, each one trying to name a feeling most of us recognize but rarely try to articulate. As documentarians, beauty is not on anyone’s KPI list. But we all know it when we see it, and this group of community members made a valiant attempt to describe it.

The first thing that comes to mind for most people when thinking about beauty and tech docs is visual presentation: consistent patterns, colors, images, and use of whitespace. But anyone who has wrestled with separating content from presentation (DITA, anyone?) knows there is a distinct beauty in each element. There is the beauty of architecture: logical structure, sensible information architecture, clear navigation, and powerful search. And there is the beauty of the writing itself: clarity, concision, accuracy, and flow. Put together, you have something that’s fit-for-purpose. One contributor put it most economically: “Beauty is when a shared link in our Support channel answers the question and closes the thread.”

Then there is the kind of beauty that’s harder to pin down, an intangible quality that elevates technical documentation from functional to something more. One contributor said beauty comes when documentation pulls you in unexpectedly: “It’s compelling. I’m drawn towards new possibilities.” Another contributor noted that a beautiful proof in mathematics isn’t just valid, it connects interesting ideas in a way that’s really pleasing; great docs do the same. Some technical writing does the seemingly impossible by making the audience “feel smarter, not dumber.” Beautiful docs gracefully remove barriers from understanding and unfold concepts that lead to an “a-ha!” moment.

For inspiration, Write the Docs has resources on writing, information architecture, and design and UX. How do your own docs fare on the beauty front?

To recommend or not… that is the question

Documentarians are concerned about providing clear, correct, and concise content for readers. In a recent discussion, a concern about using terms such as “recommend” or “strongly recommend” elicited negative feedback. Many felt that these terms are not clear. Some suggested using “must” (instead of “strongly recommend”) when “required” was implied and “should” for “recommend” (as an optional process).

One person mentioned not using “recommend” with any content because of liability issues. (If the customer doesn’t follow a recommended procedure, could it violate a service agreement?)

Many contributors argued that adverbs and adjectives in general often introduce ambiguity or subjective interpretation. (What does “strongly recommend” really mean?) Generally, documentarians minimize unnecessary words (such as “strongly”) primarily for clarity and conciseness. With a global audience, secondary language and translation concerns would also suggest eliminating unneeded words.

Suggestions focused on providing readers with unambiguous content:

Only document the recommended procedure. (Only provide alternative procedures for specified use cases.)
Include admonitions (Warning, Important, Caution) about possible issues.
Replace vague language with concrete explanations or examples.
Give specific numbers (such as 5) or a range (such as 1–10) instead of “a few” or “large”.
If you use the term “best practice”, provide a reason for preferring that procedure.
Use direct, active phrasing (“you must” or “you should”) over passive constructions (“it is recommended that…”).

The Google developer documentation style guide on prescriptive documentation and the Microsoft Writing Style Guide discuss using “recommend”, “must”, and “should”. (Although both suggest “we recommend”, which is discouraged by many.) In general, be consistent across your documentation to avoid any confusion and minimize extraneous words.

See more Write the Docs resources about specific writing questions.

Evolving job titles

A recent question was asked about possible replacement job titles for “technical writer” in light of industry layoffs and key stakeholders misunderstanding this role’s responsibilities beyond just “writing.”

Some suggested adding “engineer” to the end of a job title can lead to higher compensation and also highlight the strengths of technically oriented documentarians, such as creating system prompts, writing UX copy, and maintaining docs infrastructure. One respondent noted that introducing new titles into the lexicon (such as context engineer) may confuse leadership and recruiters, pushing away understanding of our roles. For example, some people commonly associate “engineer” with someone who has professional ratings or certifications.

Another concern is how to address the perception that writing is no longer valuable within the context of LLMs (see What’s in a role name after all). For one company, hiring for UX Content Designers has been trending upward, suggesting that these titles may be resistant to automation. Depending on who’s being asked, a “technical writer” comes equipped with specialized content-building skills or is associated with front-end skills and dealing with Word and PDFs.

Some expect to solve the public relations issue surrounding the role title and its associated value by owning the narrative around writers’ impact across a company. Documentarians are well-suited to influence AI-powered tools through concise language and eliminating ambiguity. People mentioned that, at the end of the day, documentarians write docs for people to use products with ease. Quality work in this domain remains clear, precise, and consistent.

Overall, respondents agreed that your job title may change in accordance with how you self-identify throughout your career, or in response to a tailored job search for a position that interests you. Solidifying value within an organization takes continual ownership through communicating and being vocal about the issues that affect those values.

For more thoughts on job titles, see the following Write the Docs resources.

See more Write the Docs resources about jobs and careers.

Write the Docs resources

Write the Docs offers lots of valuable resources related to documentation. See all of the Write the Docs learning resources. To discuss any of these ideas or others related to documentation, join the conversation in the Write the Docs Slack community in one of the many channels.

Events coming up

7 May, 18:00 PDT (San Francisco, USA): State of the Docs Panel — Sponsored by GitBook
12 May, 20:00 EAT (Nairobi, Kenya): Seven habits of increasingly technical technical writers
13 May, 18:00 CDT (Austin, USA): Write the Docs ATX Social Event @ Cherrywood Coffeehouse
13 May, 17:00 MST (Phoenix, USA): Technical Writing for the Semiconductor Industry
14 May, 17:00 MST (Phoenix, USA): May Happy Hour – Write the Docs Phoenix
15 May, 08:30 EDT (US East Coast Virtual): Write the Docs East Coast Virtual Meetup
21 May, 18:00 BST (London, United Kingdom): Build Your AI Docs Strategy: Gaps, Playbooks and Automation
27 May, 16:00 CST (Mexico City, Mexico): 🤖 Agentes de IA, ¿cómo los usas en tu documentación?
29 May, 08:30 EDT (US East Coast Virtual): Write the Docs East Coast Virtual Meetup
29 May, 09:00 EDT (New York City, USA): 💐May WTD NYC Coffee Meetup
3 Jun, 18:30 CEST (Barcelona, Spain): Collaborating with OSS projects: OpenTelemetry Docs