Only Interesting Conversations:

The Symbiotic Relationship Between Docs and Support

Matthew Buttler


Gastropub semiotics Wes Anderson McSweeney's DIY next level. Narwhal biodiesel DIY mumblecore flannel, gluten-free pork belly trust fund farm-to-table High Life keffiyeh semiotics. 8-bit artisan



Somewhere deep within your organization there are people that need your help. They might be squirreled away on the sixth floor in a darkened office somewhere. They might be in Dublin, they might be in Bangalore, they might even be sitting in an apartment six blocks away from here.

These folks are experiencing where your products, or platform, or service really is used. Where the rubber hits the road. I’m talking, of course, about your support department. And they are having conversations.




Over the phone.





Over chat.






Over Email


And they are very bored.

Symbiotic Relationship Between

Documentation & Support

My name is Matthew Buttler, and I want to talk about the symbiotic relationship between documentation and support.

Mostly I’m here today to ask you to help.

Only Interesting Conversations.

I want you to help by offering the means to have Only Interesting Conversations

O. I. C.


(Oh, I See.)

Who is Matthew Buttler?

Ottawa, Ontario (Capital of Canada)

Technical Writer / Web Developer at Speedyrails

Background in English Literature

Twitter: @diversecauses


First, a little about myself: I’m from Ottawa, Ontario, which is the capital of Canada, which explains why I’ve got a weird accent. I am a technical writer and web developer at Speedyrails, a cloud hosting company with data centers in exotic locations like... Vancouver, Toronto, and Montreal.

I’ve been a documentarian for a few years now. I’m one of those English Lit students who learned how to pay his bills through technical writing.

What has he done?

In my career I’ve worked for a few different organizations, each with its own unique set of challenges and interesting conversations.

What has he done?


A long while back, I worked for Shopify, in the wild west days.

Hello Friends, Hello Andrew, you can sit down

What has he done?



I did some work for Adobe, where I focused primarily on auditing and correcting internal documentation, I have also picked up a couple other gigs here and there,

What has he done?



Buncha WordPress Sites

like adding content or doing web development on some Wordpress sites,

What has he done?



Buncha WordPress Sites

Will Write Lab Tuts 4 Money

and this time last year I was on a short contract doing developer-oriented tutorials for a very large tech corporation.

What has he done?

High-Tech Startups

(Because... well... Ottawa.)

I find myself mostly working with startups and small companies who were in the push to get to market, or to further their market share. In order to get to market, or expand their share, they’d parachute in a writer, like me, to add self-help for onboarding new users, and fixing other sticky situations.

What does he do now?

Technical Writing and Web Development

At Speedyrails

I’ve found a very good fit in a combination role: product documentation and web development, which is what I do now at Speedyrails, again, a great cloud hosting company.

What does he do now?

Write The Docs Ottawa (#WTDYOW)

Documentarians Unite!

I’d be remiss if I didn’t mention that I’m also the lead organizer of Write The Docs Ottawa, a grouping of Ottawa documentarians. We are engineers-turned-writers, fresh graduates from technical writing programs and yes, even some STCers. We meet every month at a pub to sip cold suds--or soda-- and swap war stories, and talk about the wide world of writing.

It’s a wide world*

Disclaimer: I am not a flat earther

And it is a wide world. Though the range of companies I’ve worked for are mostly in high tech, with a few exceptions, everyone I’ve talked to about this have encountered or had similar stories coming from customer facing roles of all stripes:

I’m sick of telling people about this.

“I’m sick of telling people about blank.”

I’m sick of telling people about




I’m sick of telling people about

Account Payment

Account Payment.


I’m sick of telling people about

Password Resets

Password Resets.

I’m sick of having

Boring Conversations

You know, boring conversations.

I know this first hand.

Matthew Buttler:

Former Support Agent

It may not surprise you at all to learn that I used to be one of these entry level folks. I used to be a support agent.

There was a time in a previous life where I too was one among many phone jockeys who wanted nothing more than to put in their x hours, or y phone calls, and found myself having the same conversations over and over again.

Set your A record to


“You have to set your A record to our IP-- one nine twoooo point one nine six point... point, like dot? Like a period. The button beside your question mark key..”

Click on “Account Billing”

and enter a valid credit card.

“Click in your settings, and click on account billing. Just click into the credit card field and add it there..”

Click “Forgot Password”

For the love of cheese,

just click “Forgot Password”

“Click the “forgot password” link. No, not that one. The one that says ‘forgot password’. That’s right. You’re not in front of your computer? You’re driving down the freeway? You know what? Let me send you the reset link.”

And every day my colleagues and I waited for that


The last


last call


The last



The last chat


The last




That last email in the queue, hang up

exhale deeply, click resolve, and desperately wish there was an easier way to work with these... users.

And I’d open a fresh can of Canada Dry club soda and I’d think about ways to make things better for everyone. To have, instead of these boring conversations of a time when I would have... only... interesting conversations.

O. I. C.


The domain problem

I’m going to tell you about a specific boring problem that I faced many times: Way back before I was writing documentation for a living, I would often encounter this “Domain” problem, something I found the most boring, and so it’s near and dear to my heart.

Custom domain

The task seemed simple enough to the developers, and the workflow was straight forward-- apply a custom domain to your account with the software.

Let’s close our eyes and imagine, if you will, that you’re sitting in an aeron chair in front of a screen, and your headset starts to ring.

So you pick up the call, and, like I said, the user wants to add their custom domain to their website. They want to use this domain because they’ve been using for eighteen months to build some hype, and they want that domain name that they bought last year on sale to link to

their site they’ve just built, or their application they’ve finished developing,


(mmm... pizza)

for their online pizza delivery service.

How Do I Domain?

So you think to yourself, fantastic, that’s great, it’s not too difficult. But to normal people, users in the pizza delivery racket, it’s one of the most technical things they’ll have to do.

The problem here, of course, lies in the fact that it’s often a third-party.

And while I could name names, I won’t, some domain hosts are complicated. There’s added friction for the user, too, because it’s not directly under the umbrella of the platform that you’re paid to support, and often the domain provider is

Misleading UI

trying to upsell some hosting space through aggressive branding, or

No direct thing about the thing.

didn’t provide a clear Knowledge Base article about how to do this thing that they need to do..

So being... ahem


resourceful enough to pick up a few domains from some of the popular providers, I had learned as much as I could about this very common task.

Do the thing.

One by one, I navigated the dark corners of their DNS controls, and after some time I had the coveted, rarified knowledge to solve the problem, but it was still leading to boring conversations:

Still boring.

“Click ‘My Domains’, Click ‘Edit Zone’, yep, click the third line. Click the green tab, okay, you should see... a page titled edit zones”

You get the idea.

The gap, while I had it filled in my case, still existed, but the boring conversations were still happening across the department. This knowledge gap was still eating up valuable conversation time, and it’s still 30% of my day, and everyone was coming to me for the expert opinion on domains.

So I got to work,

Write the thing.

and started documenting, what I knew, and, wouldn’t you know it, it really pays off to have stuff written down, and it really pays to be able to provide direct links to people to solve their own problems.

And now that we had it written down, the conversations started to become less frequent.

Fewer Conversations about the thing.

The gap had been largely filled in. A lot of people could look it up in our knowledge base, because it was clearly marked. And the conversations we were still having about domains usually lead to more valuable of a call. You build confidence in your product.

“Oh, you’ve bought a domain on NameDaddy? Yeah, sure, let me send you our documentation. It’s got screenshots, it’ll take you through the process from start to finish. Anything else I can help out with today?”

Then an actual problem might arise:

“Well actually, yes. Here’s a complex problem that I’m not too sure about, can you help me with that?”

O. I. C.


Interesting Problems.

Conversations became more in depth, more worthwhile, and the support team became more robust. More versatile, and able to broaden their knowledge beyond the simple A B C; the team was evolving, and becoming more adaptable and able to handle “interesting” problems,

Interesting Conversations.

Having interesting conversations


Interesting Conversations.

Only Interesting Conversations

O. I. C.


Docs as a toolkit.

Documentation started acting as a toolkit, providing a means to stop the same question from coming up over and over again without a standard solution, and support began encouraging customers to, well, read the docs. *wink*

And as trust started to build, I started to notice that the relationship was




We were experiencing symbiosis.


What is symbiosis?


Two different organisms living in

close physical association,

typically to the advantage of both

As a dictionary definition, because that’s who I am, it’s interaction between two different organisms living in close physical association, typically to the advantage of both.

Think about those birds that you see in nature documentaries that hang out around rivers and pools who land on large animals and pick the insects off of them.

These symbiotic birds, oxpeckers to be specific, land on a hippopotamus,

or zebra,

or rhinoceros,

and feed off of the insects the animal’s picked up over the course of their day. I bet if you’ve ever seen a hippopotamus, you’ve probably, at some point or another, seen a picture, or a video somewhere of a bird cleaning off a hippo.

They land on a hippo’s back, find the bugs, and pick them out, and get fed

In the process. It’s great symbiosis


So we have two different kinds of people, documentarians and support agents, working in close physical association to the advantage of both. It happened to be that I was co-located in the support department, which was pretty handy as it gave me a ground-level view of what was going on around the watering hole. These minor conversations where agents would talk about


Boredom and




And boredom


And repetition

Do the work.

so I started listening, and asking questions, and seeing how I could help out.

I started searching for bugs that were easy to find and easy enough to fix with a little bit of documentation.

Develequis Genericus

Oxpeckers can clean off zebras

DevOpseratos Maximus


Marketoros Dubious

And wildebeest as well, but

Supportos Heroicos

I’ll get to those animals in a minute.

But here, we have on one hand your support team, lumbering around, and wading into unknown waters,


sighing about another phone call about whatever,

and tech comm as birds on their back, reducing friction, and removing pesky problems.

I need to do other things.

I can hear you saying “well that’s all great, it seems so obvious, but I have other obligations, and other things that I need to do. I have APIs to document for zebras, I have products to document for rhinos, and I have fabrications to make for wildebeests.”

These things are also important

I get it, and it’s tough, but you can make the case for this kind of activity. Let yourself sing the sweet song of success to your boss.


Success for the boss, success for us, success for support, and success for the customer.




Which is success for business, which is something we can be pretty happy about.

This is not unique.

After some time, I found myself in a different organization hearing the same complaints

from a different audience about boring conversations


(One Time Passwords)

authentication with one time passwords,


“It works on my machine...”

or stuff like inconsistencies in dev environments-- you know, the “It works on my machine” problem,

How can I help?

So I became focused on the patterns that were emerging that were the source of our problem.

So again, I started landing at desks, asking what I could do to help, and filling my beak.

This became very important as my career continued and I kept finding myself in new territory, working at a different organizations, with entirely different animals, but still hearing the same kinds problems were happening over and over again, only this time from different angles, and with different animals.

Common Problems

and how to categorize them

What Problems?

Knowledge Gap.

These are some of the easiest issues to solve.

Actual, real


And I would never write FAQs. I made that promise when I read this question as a Frequently asked question:

“.zip files, what should I know?”

Knowledge Gap.

These conversations can go something like: “Hey I need to know how to configure our VPN so that I can do the thing, but there’s no doc on it, and I super don’t want to call the help desk; I’ve called them like four times this week.” This was draining time, and resources of other employees, for which there could have been a better guide.




“These are fine.”

These are the “Hey, these instructions don’t line up with what I’m seeing” and “I got to step six but it was already configured, but I got scared so I stopped.”

“No, they ain’t.”

A bit more complicated, and you might need a to justify the time you’ll need to amalgamate, centralize, and prune off old docs,

“Oh, I see.”

making it easier to digest.

Unfindable Docs

These are pretty tricky, and often it relates to how broken a KB’s search tooling is, which

Broken Metadata

involves digging into metadata. These are documents that while searching for the actual thing won’t find it at all, but if you happen to know the secret word, like monogram, it’s the top result.

Slow Boils

These are a personal favourite of mine, where you see some real ingenuity come into play from people, where you’ll see a rails console open, or some weird custom patch that isn’t widely distributed.

“These are fine.”

“The error message is still showing at the bottom of the screen? And you can’t click ‘finish’? Pull all the way up on the iPad, and click ‘finish’ when it comes out from behind the banner.”

“Oh, yeah, that feature isn’t implemented yet. Let me enable it for you on my side.”

“Just ignore that screen, and click ‘take me back to classic’”

“No, they ain’t.”

These are also cases where developer help is desperately needed, but no one affected seems willing to jump the gap between silos.

“Oh, I see.”

That’s something unique to our role.


and where to put them

I’ve heard many conversations about where documentarians belong, and it’s often related to the kind of company you work for. Some are in engineering, some are in support, but really, you have to think of it more like a bridging between departments.

“Please write the thing.”

Often, writing departments are small, and in my case, I’m the only one at my current job. So often we need to have high mobility. We have to be unintimidated by the developers who have the ability to fix the thing

“Please fix the thing.”

We have to explain that the rails console isn’t a realistic option, and that, by gum, the UI needs to be fixed.

Colocation, Colocation, Colocation

I said I was co-located which is a great advantage to have. An important part of my view on this this is proximity

High Level View

but the ability to see it from a high level, track trends and make some friends and allies along the way.

Get a few people you trust to be your insiders on the ground who can flag common problems. Show up one day and ask to shadow someone, or just see what’s bugging them.

Bring Donuts

Bring donuts. You’re a hero. It’s great.

From my experience, boring conversations are always a trend that happens. You can probably find a data set about them all, but sometimes they creep up and you don’t even think about them.

It’s important to remember what we’re aiming for here:


worth having.

Conversations worth having.

Only Interesting Conversations.

Only Interesting Conversations.

O. I. C.


Mitigate, Mitigate, Mitigate

Get the information that you need to mitigate the big problems.

I haven’t said this directly

I haven’t said this directly, but this goes both ways.

You can take your perspective and go find the zebras working on the next big thing, pick their brain for a half hour, and bring features down to the watering hole

and share information to the relevant hippos or, yes, even wildebeest, and share it early and often.

People love to hear about the next big thing, especially when it’s seen as a fix to a slow boil. Support agents especially want to see what’s being worked on, and often agents can provide valuable insight into how to make sure the objectives can be met.

“Where are the donuts?”

I’ve found that a lot of the time support staff are often undervalued,

“Where are we?”

even though they’re savvy, and know their way around the wilderness.


Domesticated user testing can give you an idea of how the new feature will look to some customers. It “Looks Good To Me”, folks will say.

Does not LGTM. Nothing here LGTM.

but until you see how it works in the wild, you might be overlooking an important issue, like nobody using that button, or there’s a bug that affects users with a specific condition that wasn’t incorporated. Not all animals have the same understanding as others.

Mobilization is a Sensation

So mobilize. Find some different animals to pick at.

And one hundred percent of the time you can come away with something that’s really buggin’ em, like out of date mobile docs, or out of date screenshots for Godaddy, or like,


what the heck does this microcopy mean?

Turn the

thing on.


Things need fixing.

These are the things that need fixing, and it really helps, no matter how small the change might seem to be. It builds trust not trust in you, but also for your product.

Remember, be like a bird, come in from a high level and see what’s up.

How can we tell


things are fixed?

How can you tell if you’re making a difference, though? I mean, some people don’t notice the birds; if we do our work correctly, it should be seamless, right?

And we’ve talked about measuring the impact of documentarians and documentarian interventions in support here on this stage before. There are many metrics you can point to that indicate success.

Short is good

Short is good

Hits are good

Short is good

Hits are good

Time is good

They stopped calling?!


Things look good. They appear to be good.


There’s a problem with these measurements. It takes time to run metrics you pull from an administration dashboard, or listening in to every call all of the time, and ignoring the other animals, it’s hard to get a sense of whether or not you’re making an impact. Sometimes you gotta read the emails to know what’s up, or you gotta read the chats to see how it’s going.

And an interesting conversation inherently leads to a longer support interaction.

Oh, I See.

I see.

And asking people all of the time what their problems are gets pretty boring, too. Whenever possible we’re looking to have only interesting conversations.

O. I. C.

O, I, C.

It could be bad.

Really what you’re looking for is a lot less measurable than that, and it could mean bad things.

It could be bad.


It could be bad.

KB Feedback

KB Feedback

Rating: 0/5

Comment: Not appropriate for this talk.

Social Media

Grand Prix

Be Visible.

People might not know you’re there, or what you do and what you can do for them in particular.

Be Visible.

And I’m not telling you to fix everything and run yourself into the ground. It’s frequently little things that needs a little attention, and they can lead to great things with just a little extra push.

I need to do other things.

And like, I respect you have other things to do, too.


What you’re really trying to build here is trust:

Trust between your customers and your support agents to get accurate, complete, and concise knowledge quickly, ideally making your customers bolder, and trusting themselves, and saying “I don’t need to get on the phone, I can figure this out myself.”

But also trust between your support team and, well, you. You’re someone outside of the rank and file that has their back, and you’re driving home the point that you’re a good person who cares.

I can’t say this enough, Trust is the cornerstone here. It feels nice to know that someone is looking out for you, and that Trust is part of what makes it so good.We are here to empower our audiences to have Only Interesting Conversations.

O. I. C.



And if there’s one point that I can drive home here, just before the end of the first day of Write the Docs, is that our job isn’t just merely to document products, APIs, blenders, or beehives.

It’s to build trust with our users, confidence in our agents, and empower everyone we can, so that they too can say to themselves:

Oh, I See.

Oh, I see.

Only Interesting Conversations: The Symbiotic Relationship Between Docs and Support - Google Slides