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:
- The State of Unassisted Support 2014, Technology Services Industry Association (TSIA). Includes a graph that compares the cost of self-service support with the costs of other methods.
- A Good User’s Guide Means Fewer Support Calls and Lower Support Costs by Cathy J. Spencer and Diana Kilbourn Yates. GE Information Services saved $1 million in support costs per year by providing good user documentation with software products.
- Currents, A Seasonal Report on Developer Trends in the Cloud: Open Source Edition, Digital Ocean. For open source technologies, great documentation can reduce the barrier to entry for contributors, and it’s something companies are looking for when they evaluate open source products.
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¶
- Amazon CloudHSM Doc Writer
- Amazon - Herndon, VA or Seattle, WA
- Lead Technical Writer
- Deskpro, London
- Technical Writer
- Wowza Media Systems, remote
Find more jobs on the Write the Docs job board.
Community events coming up¶
- 04 February - Portland, OR, USA - Joint meetup with Support Driven: Knowledge-Centered Support
- 13 February - Leeds, UK - Book club: The Product is Docs
- 18 February - Melbourne, Australia - Writing about Security Incidents, and Season of Docs
- 19 February - Toronto, Canada - Write the Docs Toronto
- 20 February - San Francisco, CA, USA - Lightning talks
- 25 February - Ottawa, Canada - Write the Docs Ottawa
- 25 February - Sydney, Australia - First 2020 meetup
- 25 February - Brisbane, Australia - Write the Docs Brisbane kickoff
- 05 March - Stockholm, Sweden - Write the Docs Stockholm #3