How Our Documentation Team Uses Slack
First things first, yeah, I know that using Slack is hardly a revolutionary idea. It’s been around long enough that just about everyone uses it. I just want share how our documentation team uses it.
We have a channel, available to everyone in the company:
#documentation
This is the documentation announcements channel. Innocent enough, right? It looks very unassuming, just sitting there. But it’s powerful, trust me.
The basic purpose and use of this channel is straight forward.
We post here when we publish a new article, so the greater team knows we’re alive and kicking. We call out (@) people who help us, whether it’s a dev who shared info proactively, or a QA Eng who helped review the text, etc., etc.
This kind of recognition is positive reinforcement in digital form. Devs (and other folks) like seeing their name in a positive light. They notice when their teammates get kudos and, I like to think, sometimes they maybe get a bit jealous. Maybe they want a little of that sweet, sweet attention. Since we started naming names, we’ve had a noticeable increase in participation from folks on other teams.
We do a monthly “What’s new in the documentation” post, where we summarize the larger updates, new articles, and stuff like that. We usually point to the other posts from the month, maybe mention some of the things we’re working on for the next month, stuff like that. It’s also a place where we can display our team’s personality.
That’s the basic use. But there’s something more.
We’ve overloaded the channel to do something a bit unorthodox: all of the documentation article/page up *and* down votes are shown here, thanks to a handy Slackbot we convinced a friendly engineer to write. Now, you may or may not want to provide that kind of visibility and “how the sausage is made” info to the rest of the company. This is a choice we made, to show the feedback as it arrives, warts and all. We take the docs seriously and want to make continual improvements. We also want the rest of the team to know we’re on the case and that we don’t have anything to hide. This can be difficult to bear sometimes.
When we had an upset customer go through and downvote a dozen of our pages in under 2 minutes, everyone in the company (well, everyone who subs to #Documentation anyway) saw it happen in real time.
This has turned into an interesting and overall positive experience though. When we get an up vote, people see that and give us a thumbs up or reach out with comments like “Oh, I send customers to that page all the time!”.
When we get a down vote, they take it as an insult. They want to protect us, and also help diagnose the issue. Was it just a grumpy reader? Or is there something missing or incorrect on the page? We got a lot of helpful, internal contributions just based on down voted pages. We’ve had Sales and Support engineers reach out to customers on our behalf.
Now, this is just one our docs-related channels, and I’m sure many of you use Slack for all sorts of interesting things (tell me some in the comments!). I know of one large TPubs team that has many slack channels, including one just for discussing jargon. Ultimately you’ll want to walk the line between having too many, very specific channels, and too few, overloaded ones.
I wanted to share this one use, this particular instance, because I love how much value we get out of a single channel: community, reward, recognition, assistance… It’s all just a Slack channel away.
