Home »

Write the Docs Newsletter – February 2020

Happy 2020, documentarians! It’s Beth and the newsletter crew here, with the latest and greatest from the Write the Docs community.

Two items on the news front today. In December we announced dates for the Prague conference, which will be 13-15 September - and in a brand shiny new venue, the Hotel Olšanka! Read all about it here. And across the pond, the speakers for Portland speakers will be announced soon, so keep your eyes peeled for those. The conference is 3-5 May, and tickets are on sale right now.

So with that, let’s see what’s been cooking on Slack recently!

#learn-tech-writing book club

There’s been a buzz of activity all through January in the #learn-tech-writing channel, where folks have been discussing The Product is Docs chapter by chapter. Participants have started a writeup of all the fantastic conversations the discussion produced, so we won’t duplicate their efforts here. But here’s a list of what they’ve produced so far:

If you’d like to help out with write-ups, drop into the channel! As a bonus, they’re looking into what to discuss next, so if you have a book you think would be great for group discussions, go ahead and make the suggestion.

Supporting documentation, documenting support

A recent question about how to balance docs work and support content produced an unexpected range of responses. The original post assumed two different teams producing distinct content - one creating documentation, the other working on articles for support. This is evidently the situation in many companies. For example, one poster described a workflow where answers to frequently-asked support questions are added to the documentation, but if a potential docs page seems particularly complicated, or addresses an edge case, the writer asks support to document it. This story describes distinct teams – Docs and Support – and distinct types of content.

But this may be a rare privilege; many replies to the original post were from people who work on support teams, not on dedicated docs teams. And they write the docs. In their situations, there isn’t a clear distinction between roles, nor between types of content. More than one reply described scenarios in which all docs are produced by support.

Still other replies came from technical writers whose role emerged from support. Some writers report to a support manager, and some people in a dedicated writer role work from support tickets, to make sure the docs address known customer issues. Some folks work on both product docs and separate knowledgebase articles.

In short, there are myriad ways to organize the relationship between docs teams and support teams, and between the different (or not-so-different) types of content. What everyone seemed to agree on, though, was the need for close and well-coordinated communication across teams and deliverables.

How to set priorities on a documentation team

So you’re no longer the only documentarian in your company. Hooray! Working in a team allows you to tackle bigger and more complicated projects. But how do you decide what to focus on, especially for new team members? This month, our community discussed what helps them set priorities:

  • Discuss the project’s roadmap with project/product managers, and ask them (and other stakeholders) about immediate documentation needs. For your new writers, ask about topics that could use a little extra attention - an opportunity for them to specialize in something.
  • Encourage new writers to sit in during backlog grooming and project demos. Product prioritization can inform your own priorities.
  • Coordinate with engineering teams by attending their standup and planning meetings. You’re working towards a common goal, so it helps to know how everyone’s contributions fit together.
  • Try an issue tracking tool (eg Jira or GitHub Issues). Some feel it helps keep them accountable and prevents them from struggling under the workload. Similarly, for big projects, try mapping them out using a tool, to give your team and managers a high-level glance at everyone’s workload.
  • Set up a mandatory flag or field to say if an item needs to be in the release notes. This ensures that important items and fixes won’t go undocumented.
  • Audit your docs, archiving or updating content that people aren’t reading. Alongside PMs, determine which content is outdated or unnecessary, and then divide them among writers on the team. And if you’re struggling to persuade colleagues that an audit is necessary, our next article might just help.

The costs of outdated docs

This month’s discussions included a brief but fruitful conversation about the tangible costs of outdated, inaccurate, or just plain poorly written documentation. It can be helpful to keep data about the value of good documentation on hand, and our documentarians turned up several reports and studies to consider:

When you find inaccuracies in your docs

Although we strive to write accurate documentation, inevitably there are times when errors are made that require addressing. This month our community talked about what to do when you realise there are inaccuracies in published articles.

The question of blame is unavoidable. Should writers have their work scrutinized for small errors? Many felt problems in documentation should rather be attributed to process failure. If you have to complete a document to a tight deadline, you may not have enough time to check it properly, resulting in faulty docs. Others didn’t want to frame it as a failure: just a chance to improve both the doc and processes. But even if you have a good pre-publication process, errors may arise from other factors: for example, testing the docs but within the wrong environment, meaning they don’t match the end user experience.

What most agreed on is that the documentation should be revised and corrected as soon as any errors are discovered. If errors are a big problem, teams can establish a process of reviews and approvals to check for accuracy. Another option suggested was to have QA test the documentation.

However the team chooses to address the errors, it’s important to acknowledge the mistake first and then outline a plan of action; focusing on blame may take away from what could be a learning experience for the whole team.

Job posts

Find more jobs on the Write the Docs job board.

Community events coming up

Write the Docs 2019 Stats and Community Update   Announcing sessions and opportunity grants