Home »

Write the Docs Newsletter – November 2022¶

Hello once again from the newsletter team. There are many things going on in the community right now.

I wrote last month about opportunities to get more involved in the Write the Docs community, and this month sees more information. A new Write the Docs Enhancement Proposal has been opened to provide more clarity on Write the Docs teams and what they do. The change also includes Mikey Ariel stepping down as Prague conference chair and starting as Community Board chair. While I’m sad there won’t be a conference very near me next year, I’m excited for what she’ll bring in the newly defined role. In related news, we have the dates for conferences in 2023 that you’ll probably want to save.

Of course, 2022 isn’t over yet and there’s still the exciting Write the Docs Australia conference to come. The full schedule has just been announced, so check out all the interesting talks. There will also be workshops led by people from The Good Docs Project. Be sure to get your tickets soon as ticket sales close at the end of the month.

In addition to the conferences, Write the Docs also runs yearly salary surveys. These are a great resource for seeing where a salary fits in the overall industry, which should help you in any salary negotiations. Answers are always anonymous. Contribute your information to the 2022 salary survey.

Outside of these wonderful community efforts, we had lots of interesting discussions in the Write the Docs Slack this month on goings, comings, and many things in between.

Knowledge transfer for documentarians¶

Whether you’re moving on to a new job or taking extended leave, it’s a nice touch to try to smooth the transition for your coworkers and help your replacement find their footing. As documentarians, we’re certainly well prepared to document what we do and how! Beyond documenting how to write, publish, and maintain the docs, add these ideas to leave your current team and the person who’s replacing you in the best possible position.

Organize your work files so that naming conventions and folder structures all make sense.
Invite your coworkers to schedule Q&A sessions with you.
Leave a list of work in progress, known to-dos, and ongoing issues, with the context and status for each.
Write an operator’s manual for your job with “insider” information such as company jargon, required tools and credentials, names of SMEs and other helpful contacts, best methods for collaborating with different teams, and other institutional and tribal knowledge.
Clean up any docs debt, such as broken links, orphan topics and images, outdated Git branches, and docs-related tickets and issues.

Joining as a manager¶

On the other end of transitions, our community recently discussed what a new manager should do within their first few months of joining an existing technical writing team.

Many people advised spending time getting to know the team, team members’ strengths and weaknesses, processes, existing docs, and where the team fits in the overall organization. One person suggested extending that to focus on not making any changes at all for a while. Take the time to understand the entire context and all expectations from the team and the rest of the organization before committing to anything new.

As you’re evaluating the context, consider where you need to form relationships around the organization to help the team work effectively. Find out what business goals the team helps with and what needs other teams have that the documentation team could help with. Learning this context helps you determine how you can best advocate for your team.

As you learn how to advocate for your team, think about how to grow it to meet the needs you discovered. This can mean helping people with professional development or figuring out who can be hired and how to get the budget for that. Creating a long-term plan based on what you determine in the first few months can help you place your team needs in a context that will help get them addressed.

Minimum viable documentation¶

Minimum viable documentation is the minimum required information that’s usable and helpful to users. For many reasons, it’s seen positively by some and adversely by others. Those who support it say it’s the best place to start if a product lacks any documentation. Additionally, in places where releases are frequent, such documentation enables you to write the essential information and then return to the document to update it once things have stabilized. But there are competing views on minimum viable documentation, and those who work at places without it believe that the “document everything” approach can lead to many issues, including leaning more towards a mindset of “done is better than perfect.”

Proponents of minimum viable documentation consider that a product should be capable of functioning with little explanation from its authors. They say this provides a quicker turnaround time on new features, enables faster bug fixes, and simplifies developers’ lives by removing tiresome writing duties. Opponents claim that this strategy results in varying quality across products and can lead to knowledge gaps within teams. They argue that all software should be documented since it eliminates uncertainty when using new systems (and makes life easier for users).

If you’re interested in learning more about minimum viable documentation, read this blog post from Sarah Moir. It covers defining such documentation, assessing documentation states, and structuring documentation.

Choosing a style guide¶

There are plenty of style guides out there. But if you want to pick one to follow, how do you choose what’s right for your team?

Our community had a few thoughts on the most well-known options. If you’re writing for the average consumer, the Microsoft Writing Style Guide is worth considering. For a developer audience, the Google Developer Documentation Style Guide has a tighter focus and so might be more useful. For open-source projects, the MongoDB Documentation Style Guide might be a closer fit for your approach or voice.

But they might also not be a good fit for you. The style guides mentioned above may be extensive, but none of them aim to be universal. They’re each designed by a company to meet that company’s needs and serve their customers. You could consider writing your own – but writer beware. It’s a huge effort to create a new style guide. One documentarian saw it take two people three years to release a company-wide guide, and the project continued past that. It’s not to be taken lightly, and there is usually more urgent work to attend to.

A middle ground is to pick an existing guide, and then adapt! Several documentarians mentioned that they chose an external style guide, and now maintain a short-and-sweet extension to it. It can be as simple as a sheet or doc that lists your own terms and points where you deviate from the external guide. The recommendation was to be incremental and collaborative: start with something that works for you, covering your essentials, and you can always build from there.

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: With so much focus on DEI lately, The World Economic Forum says a diversity backlash is underway. What does this mean and how can you resist it? _ A medium read: TechBeacon focuses on how tech companies are doing with DEI. They’ve found that even though there is some progress, we’re still falling short.

A large read: In November, the United States celebrates Thanksgiving. The Smithsonian explores the problems with this holiday and how indigenous people choose to, or not, celebrate.