​Power up your support team to create better documentation

April 2019

Software support teams are in a tough spot. They know documentation is important, and they love to refer customers to it, but finding time to actually write and maintain those documents is *really* hard. That endless support queue and its ceaseless demand for attention means that documentation is too often ignored. Mat shares his hard-earned practical advice to help technical writers and support team knowledge base owners create a more effective documentation system. Steve Moss sums up Mat Paterson's excellent webinar.

About Mat Paterson

Mat is a customer service evangelist at Help Scout in Sydney. Help Scout is a help desk software company, headquartered in Boston, Massachusetts. The company provides an email-based customer support platform, knowledgebase tool, and an embeddable search/contact widget for customer service professionals.

Mat spent his early career as a web designer for companies including ASX and booking.com, and briefly Sydney's Taronga Zoo before joining email marketing startup Campaign Monitor to run their customer service function.

After a decade building and running that team, and writing an enormous amount of documentation, Mat joined Help Scout where he helps companies deliver better customer service.

Having worked with a number of support and documentarian teams, Mat is keen to see them working more effectively together.

Introduction

On a recent visit to his doctor, Mat was surprised to see her googling his symptoms. Clearly doctors can’t be expected to know everything – but they do have the expertise to be able to locate the correct information in the current context and figure out what needs to be done.

This got him thinking about the connection between the people who are delivering the service and the people who assemble information into a suitable form so that it can be found and used. In his world, this would be the connection between the support desk staff – and the people who develop the documentation – the technical writers and documentarians, as he calls them.

To highlight how this connection works and its implications for us as technical writers, he discusses it in three parts:

• 1.Diagnosis – what are the problems that come up between support and writers, and why aren’t knowledge bases as good as they could be?
• 2.Three case studies: Campaign Monitor, Survey Gizmo and You Need a Budget.
• 3.Treatment options – a summary of the things you can do to improve the quality of the documentation as well as the quality of customer service.

1. Diagnosis

In his job he uses a lot of knowledgebases – some are good – others not so good. It’s not as though the poorer ones were written by people who didn’t care or who were incompetent. It’s more likely to be the result of the environment they were working in – an environment that made it impossible for them to do good work. In most start-up SaaS companies, the support team are usually the first to be hired, as support is required from day one.

Members of the support team, or even developers, can write the documentation and if the quality is not good the support team can still catch any problems that slip through. By the time the technical writers are hired, thing may not be going so well. Typically, they join the company with a difficult task – to try to ensure that the documentation is up to date and complete so that it can be used effectively by the support team. Agile development may get good software to the customer quickly, but often it doesn’t provide an agile process around creating the documentation. So small changes to the software can result in huge changes to the documentation. Mat draws a comparison here to cheese rolling, where the product is pelting down the hill with the support team and the technical writers running desperately along behind, trying to catch up without falling over and breaking their neck.

In many companies, support and documentation sometimes have a relationship where the support team reference inaccurate documentation with documents and support contradicting each other. This relationship between technical writers, support and the product team cover a pretty wide spectrum.

At one end there is an unobtainable utopia where everything is perfect, and at the other end, things are pretty bad – which is entropy and chaos. This spectrum applies to all companies and you will sit somewhere on that line.

It’s important to understand what the two extremes would look like. Let’s start by looking at the good end. This is the good place, the product team are in the middle doing their work, sending out good products to the technical writers who are producing documentation. The writers are a great source of truth about what the product does, how it works, how we talk about it and the language we use. They work closely with the support team who appreciate all those fantastic documents and the support team are also able to pull back information from the customer world; where do they need more information; where are they still getting a little bit confused? Is customer language a little bit different from our own internal language and is that causing confusion? And support feed it all back to the technical writers and this all works in a continuous loop around the product, and everything is wonderful. That is the dream: customers benefiting from an accurate and current knowledgebase, to which support actively contribute. Technical writers are a trusted source of truth and, together with support, provide the customers with a voice into the product teams.

Now let’s look at the other end of the spectrum: entropy and chaos. This is the bad place, and at first it doesn’t look that different. You’ve still got all the same pieces: the product team still producing product, technical writers are still producing documentation, it’s just that the loop has broken and everything is just a little bit disconnected and floating around.

The support team are out there and maybe have stopped using the documents because they found that they are out of date. They have hoarded their own internal documents and now there are two sets of documents, sort of competing. The product team is not really talking to support or the technical writers in a useful way, so there are big gaps in the knowledge. The technical writers are still working hard, rather like Halley’s Comet, they zoom in around the product, dump in some documentation and then return 70 years later.

In this picture the customers are somewhere out there, just floating around. They are still getting help, but not as much as they could be: this is the nightmare scenario. A knowledgebase that is out of date or misleading, which leads to support losing trust and using worse alternatives. Technical writers lose heart and disconnect from support, and the product teams de-prioritise documentation.

Where you are on that spectrum may be somewhere in the middle.

2. Three case studies

We just want to head towards that utopia, where life is peaceful, but how do we do that? To try to find out, Mat spoke with three companies who had started to move in that direction.

At Campaign Monitor, where Mat worked for nearly 10 years, they didn’t have a technical writer, so Mat wrote a lot of the original documentation. Most of that has now been replaced with new and improved versions, developed by the current tech writing team of Carlee and Craig. The product is around 15 years old, and as you know, with older products there is a lot of complexity and history to deal with. To manage that, Carlee has identified three audiences: customers who use the product, and two internal audiences – the support team and the product team. She and Craig have set up a centralized “user voice” knowledgebase that the support team can use to find information – all in one place.

As a support person, if you can’t find the information you need, there is a feature that lets the support person “vote” for the item to be updated, which allows them to priorities the change. If the information is not already there, the support person completes a form to request the changes they need, complete with details of the context. Basically, Carlee and Craig tried to make it as easy as possible for the support team to request a change.

The second thing was to close the loop with support by producing a monthly newsletter. This newsletter makes sure that each member of the support team gets recognition for their contribution, but it also ensures that all members of the team can see what’s being updated and have confidence in its accuracy.

Carlee’s final point was that, as technical writers, she and Craig both feel like they are the voice of support in other parts of the company. That’s because the support team don’t always get involved in product decisions or may get involved quite late, while Carlee and Craig are quite often in those meetings by the nature of their work. So, they consider themselves to be advocates for support, asking questions the support team would ask if they were in the meeting or to explicitly invite them in.

The second company Mat talked to was You Need a Budget (YNAB), a financial software system developer. As you can imagine, there is a really big knowledgebase, and he spoke to Michelle Wingard, who is on the support team there and asked her how they maintained that huge knowledgebase.

She explained that their first goal was to make the change process more transparent. Previously they used a big spreadsheet and it wasn’t obvious what was being updated and what wasn’t. Surprisingly, YNAB have a support team of over 40 staff but no technical writers. The entire knowledgebase is maintained by full-time support people who work as part-time technical writers. The knowledgebase is broken down into categories, and each category is the responsibility of just three or four people. Each group has a team leader, so it’s clear who you need to speak with if a change is required.

The second goal was to extract the knowledge of the system out of the heads of the support team and into the knowledgebase. This was especially important for the older features of the product, as it enabled newer members of the support team to build up a better understanding of the way things had developed in a historical context.

The third company Mat talked to was Survey Gizmo, who develop surveys and provide business insights from those surveys. He spoke with David Domagalski, who was a support person but later became a technical writer.

David explained that they use an agile methodology called “just in time” (JIT) documentation to maintain their knowledgebase. Here’s a quote from their blog:

“Our knowledgebase was almost entirely made up of guides written from a ‘just in case perspective’. That is, the documentation was written before the feature was released, with the theoretical user in mind; so, we had to try to anticipate the questions actual users would have. Turns out were actually pretty bad at doing this.”

Using the JIT time documentation approach, no documentation is written ahead of time. When a question comes in, the support person will answer it using other internal resources. But before they send it out to the customer, they will tick a checkbox on the form that indicates if the content can be generalized into an article that can go into the knowledgebase. Items marked up in this way automatically go into a spreadsheet, which is where the technical writers pick it up from. The technical writer then develops a suitable article and sends it back to support to send out to the customer. This process requires close coordination between the support team and the writers to make it work. David highlights the fact that he needs to know the support team really well, as he can’t really work with them unless he understands the pressures they are under. It might even be useful to sit in on a couple of their shifts to understand their job better, so that you can advocate for them and they will treat you as an ally.

3. Treatment options

So, after talking to those three companies to the get a better understanding of the relationship between support and technical writing, let’s wrap it up by drawing together some of those ideas and extract some practical options you might be able to try.

Mat suggests that the big picture is like the bees and the flowers as a sort of mutual symbiosis – this is the sort of relationship that we want to form, which is beneficial to both the support team and the technical writers. In summary:

• Less friction equals more participation – anything you can do to make it easier for the support team to provide you with the information you need will be beneficial.
• Identify and uplift your support champions – foster the assistance of a champion in the support team – someone who is passionate about ensuring that there is good documentation for the support team to use.
• Advocate on behalf of support folk – technical writers and support are natural allies, so if you support them, it’s likely that they will support you.
• Build mutual trust – work to build trust between the support team and the technical writers – maybe publish a newsletter to keep them updated about changes and to thank the contributors.
• Be specific about what you need – vague questions may never be answered – it’s much easier for support to answer questions focused on specific issues.
• Be pragmatic about how you ask for information – aim to fill the gaps – get in there and get things done in a way that’s going to work for both teams.

Great documentation is absolutely gold for support, when they know that they can send customers to the document, and they know that customers will get a good experience – one that is clear and helpful to them. Every support person loves great documentation.

But the documents are not the goal! The goal of the product or tool that you offer is to help your customer get something else done. They’re trying to get something done and all you’re trying to do with your documents is to help them towards that goal. And what they’re trying to do in customer support is exactly the same thing – just trying to help your customers get to where they’re going.

If they can do that, they will love the product and will continue to pay for it. So, support teams and technical writers do exactly the same job, doing exactly the same thing using two different approaches to do it, trying to get the same thing done.

They should be working together much more closely and hopefully this webinar has given you some ideas to help you to do that.

You can view the slides and recording for Power up your support team to get better documentation on the TechCommNZ website.