Home »

Write the Docs Newsletter – February 2023¶

Greetings, documentarians! I hope your 2023 is off to a wonderful start. Mine has been very full so far, and we’re only a 12th of the way through.

It seems to be a time of change for many. The tech industry has been laying people off, which people have been discussing from many angles. And AI has been making the rounds, with some wondering if it will replace human documentarians in the near future. Since our last newsletter, the Slack community has double-digit threads with triple-digit participants. It’s clearly on many people’s minds! Some of the thoughts are below, but I’m sure you all have more to share.

For those valuable conversations in Slack, you should know about the an update to the guidelines for the Write the Docs Slack. They should help clarify how to keep our Slack community thriving and on-topic. If you find it all overwhelming, you might find useful a description of how to get the most out of the Slack community from Felicity Brand (@flicstar).

In other news, if you’re reading this today, you still have a few hours left to get in your proposals for talks for the Portland conference this year. If you’re reading this later, you still have time to get your tickets to the in-person conference.

Thank you for all of your inspiring conversations in Slack. And don’t forget to use the :suggest-for-newsletter: reactji for your next one!

Will AI take over documentation?¶

ChatGPT is a new conversational AI tool that has been making waves in the tech community for its impressively human responses and wide-ranging capabilities. There’s been a lot of discussion – and concern – in the Write the Docs Slack recently about what ChatGPT means for documentarians. Are our jobs about to disappear?

In several conversations over the last month, the community was pretty unanimous: we don’t believe ChatGPT can do the full job of a technical writer, as it has too many flaws. Top of the list is simply being wrong: ChatGPT will merrily make things up, making statements that are not supported even by its own data. Also, it only has access to certain source material – for example, it can’t tell you what’s in your upcoming software release. One community member said ChatGPT had invented command-line flags for their product that don’t exist. It’s also not able to interview SMEs or figure out from a long technical explanation which parts are actually relevant for an end user.

That said, people saw plenty of potential in AI. There is work that is boring and repetitive, which we’d all appreciate being automated away. ChatGPT is good at creating many suggestions really quickly if you give it the information you have to work with. Some suggestions may be bad or wrong, but some could be a decent first draft. ChatGPT could also potentially help with editing – suggesting ways to make sentences shorter or more grammatical.

It’s a tool, not a replacement. Like the ‘computers’ at NASA early on – once machines got more capable, humans stopped doing repetitive tasks, went up a level of abstraction, and became computer programmers. So it’s something we’ll have to try out and figure out how useful it can be for us.

Inclusiveness in diagrams¶

Inclusivity in diagrams and visual aids is an important topic and growing increasingly so. Specifically, as documentarians being inclusive is necessary to make collaboration more welcoming. For example, what’s the most inclusive option to pick if documentation calls for emojis? Is it yellow because that’s a “neutral” option? And what about genders? These decisions helps ensure people are represented properly.

Of course, there are alternatives to using those easily recognizable emojis to represent people. For instance, you could use ones that appear to be more “blobby and amorphous.” The downside to using more abstract emojis and characters is that the diagram or visual aid may not be as compelling.

If you don’t use emojis because you dread the workload of updating them, you might not think this applies to you. But there might be instances where you notice emojis or characters in other places around your organization, such as in org charts or team member profiles. Or you might see them in workplace communications or marketing materials. One good piece of advice is to have people create their own emojis or visual representation of themselves.

When it comes to inclusive diagrams or any other visual aid, it’s best to exercise empathy and be respectful of others’ views and opinions. If something seems unclear with respect to inclusion, consult HR or talk with your company’s diversity, equity, and inclusion (DEI) team if possible.

When less is NOT more¶

Apologies to Mies Van Der Rohe who said, “Less is more.”

The #managing-writers channel had a recent discussion on layoffs. Managers are concerned when asked to downsize their documentation teams — especially when expected to maintain the same workload with fewer people. This is also a concern when people leave by choice and the manager has to justify hiring replacements. Having a smaller documentation team is particularly challenging when development teams have the same level of work on new products or features.

One suggested solution at some companies was to have the development team work on documentation. This solution was met with some skepticism. Another suggestion was to document how the reduction (for example, 20%) would affect the team’s productivity. This elicited a discussion about a documentation team’s responsibilities, which may include:

Writing new content for new features.
Reviewing existing content and updating as needed.
Resolving support requests by adjusting the documentation.
Getting (and responding to) feedback from users about existing content.
Adding multimedia to (or refreshing the UI for) existing documentation.

After determining a complete set of tasks, what can the team realistically do with fewer documentarians? One suggestion was to specify subsets of tasks that could be covered with differently sized teams.

Some managers start by evaluating their current workload (perhaps through a tracking system like Jira). Often this involves ranking existing tasks and indicating that fewer team members means lower-level ones get dropped. You can adjust assignments to make sure certain high-priority tasks got covered at least partially. Some questioned the amount of time it takes to set up effective tracking metrics, but those that do this tracking felt that it was worth the time and trouble.

Optimal number of reviewers¶

This month’s discussion brought a new twist on the challenges associated with docs reviews: How many reviewers is just right for adequately reviewing a draft without risking diminishing returns? The more reviewers you have, the more things seem to slide toward opinions and preferences instead of constructive feedback. Plus, more reviewers makes for a longer review process.

The sweet spot for docs seems to be three reviewers, each with a different focus: one for technical accuracy, one for a customer-centric perspective, and one for clarity and consistency. In terms of roles, that may mean a developer/engineer, a product owner, and another documentarian. For details about the optimal number of reviewers, folks suggested two classic articles by Jakob Nielsen: Why You Only Need to Test with 5 Users and Discount Usability: 20 Years

Reviews are most productive when all reviewers understand their focus area as well as the documentarian’s responsibility for questions of style, tone, and content placement. For more thoughts on the importance of focus among docs reviewers, check out Tech Doc: Unbearable lightness of peer-reviewing by Kristian Klima.