At Confab in 2019, Beth Dunn took to the stage to talk about moving beyond the style guide and helping writers internalise the organisational voice. I wasn’t there, but it was a talk I saw a lot of comments and praise about on Twitter. As someone who finds style guides a fascinating insight into a business and its brand, I was keen to find out more about Beth’s experience and advice on the topic.

I chatted to Beth about the style guide at HubSpot and it went so far beyond creating and sharing a style guide. They created Bethbot, an automated editor bot version that allows writers to check any copy against the style guide rules. You can imagine my intrigue. Luckily for me, Beth agreed to talk to me about Bethbot and what follows is a write-up of that chat.

Creating a style to align different teams

The first HubSpot style guide was created in 2012 when it became apparent the product team and the marketing team were developing slightly different approaches to the brand style, voice and tone. Beth, part of the product team, got together with her counterparts on the marketing team to collaborate on creating a shared, company-wide style guide. 

That was the first positive step towards aligning departments around the style guidelines and for a while, it served the purpose just fine. Fast forward several years and Beth needed to scale the UX writing work that was happening on the HubSpot product team, too.

In the early days, Beth was the only UX writer on the product team, which meant doing a fair bit of repetitive work like correcting grammar, punctuation, capitalisation and so on. That all distracted from the deeper, higher-value content design work that was needed as well. Those repetitive tasks were exactly the sort that Beth realised could be automated.

This realisation, and the need to free up her time, led to the creation of Bethbot, the automated editor bot version that allows the team at HubSpot to check any copy against the style guide rules.

Turning an idea into a slide deck, and then into a deliverable

Like all good ideas, Bethbot was thought of due to a problem to be solved. Without worrying about what would be needed and how it would get done, it was simply identified as a means to automating style guide checks.

Bethbot really came to life when Beth created a slide deck at the end of one year, charting goals to be achieved the next year. I love this mentality from Beth: ‘I didn’t see any reason why, as a team of one, I couldn’t and shouldn’t have a strategic plan for my year, too, so I thought big and set out three hefty goals for myself.’

Not only was it a cool idea to do the strategic plan in itself, but Beth also took it to the next level with a Princess Bride theme. Here’s the rundown:

• Project Montoya - create a master glossary for terms used in the product
  
  
• Project Grandpa - using the power of storytelling to engage users more effectively over their whole (sometimes epic) journey with the software
  
  
• Project Westley - creating a set of tools (Bethbot included) and resources that could stand-in for Beth, so they could scale what Beth did in a more purposeful way.
  

The strategic plan slide deck was posted on the HubSpot internal wiki. Beth said that one of the directors of engineering saw it and thought it sounded like a terrific idea. He volunteered to find an engineer who might want a challenging side project to work on and found someone the next day.

Within three months they had a beta version of Bethbot up and running. Beth emphasised that ‘getting that executive buy-in was important, but I didn’t do much to get that except coming up with a funny name to sell my idea. He got in touch with me, we had coffee, the next day I had an engineer eager to get started.’

When an idea is as strong as Bethbot, clearly the hard work is done, but having the right people involved to make it a reality was essential.

Expert collaborators and understanding the user

Once the backend structure was created by an engineer, a frontend UI was needed that would work seamlessly with people’s workflows as well. This was a key component, understanding how the people who would be using Bethbot currently work.

Adding new tools and ways of working can be considered a nuisance, even if they are offering help and making things easier. Understanding how best to integrate with and complement current workflows was essential for ensuring Bethbot would actually be used.

The second engineer involved built a Chrome extension so people could paste their copy into a field, click a button, and get feedback on how the text needed to improve or get changed, according to the style guide. Unintrusive, simple and offering a path with no friction.

A Slackbot was also built. This allowed for some fun, which Beth made the most of. Beth added a bunch of Easter eggs because ‘people get cheeky with personified bots, so you have to get it ready to be cheeky right back.’ This also brings the bot to life and makes the interactions more enjoyable. Who said style guides should be dry, boring documents hidden at the back of a drawer!

There was also a Sketch integration, so designers could check copy inside their designs, and a web app that was a big text field on a screen, with the suggestions showing up in a sidebar like the Hemingway App.

It didn’t stop there, though. Beth shared that:

The biggest thing was the GitHub integration, which is something that gets enabled in any repo that includes language strings. It’s a build blocker, so when you try to push something to production, it runs Bethbot against the language strings, and tells you how to fix any errors before it goes live. You can override it on a line by line basis, but obviously it’s best to either correct it or suggest a change to the rules if you think it threw a false negative at you for something you wrote.

Bethbot itself is represented by an image of a cartoon version of Beth:

With all the build and engineering work completed on the different versions, the next step was to involve the infrastructure team. This was to move Bethbot from experimental status to something that was safe, stable, and secure, and lived on the core stack. It was handed over after the required beta testing was completed.

Different style guides for different use cases

Whenever I chat to people about style guides, I ask about different formats. Curious as to what versions exist and who for. It was really interesting when Beth responded to this question with the insight that they ‘started creating different versions for different use cases last year.’

The recruiting team were keen for a version that would help them write more inclusive job descriptions, and to be even more inclusive in their communications with candidates.

To help with this pretty wonderful request, Beth and the team ‘set up a stand-alone ruleset that would only be used by this team, for this need, because some of the words and phrases they wanted to flag might be perfectly benign in a different setting.’ Beth added, ‘we didn’t just want to add them to our core set of rules. So we created a dropdown menu in the front end of the web app and the Chrome extension, and now you can choose what set of rules you want to invoke. Basically you just choose your role or the type of content you’re working on now — is it a job description or an email to a job candidate? Choose that menu item. If it’s product copy, choose that.’

This really is making the style guide helpful and usable for a specific user. It makes total sense given that there will be different use cases with an organisation and with those will come nuances in language, tone and vocabulary that need to be considered. Adding context will only serve to make something more relevant and useful. This has been the starting point for working on other use cases which is currently ongoing at HubSpot.

Getting people to use a style guide, and how they use it

Creating the ‘thing’ is only part of the challenge, getting people to use it is the other and arguably more difficult part of the challenge.

Having different versions for different use cases and ensuring Bethbot is part of existing workflows is a great step to making the tool usable. There also has to be some level of dissemination when Bethbot was announced, shared and introduced to the organisation. I was keen to dig into the methods Beth used to achieve this:

I did this whole presentation at Tech Talk, the big weekly meeting of all product, engineering, and UX. And I was really thrilled at the reception — I was afraid people would be really resistant, that they’d think it would slow them down. But here’s the thing: engineers love automating things. So they were in from slide one. And everyone really, really wants to create great, error-free copy.

Beth added, ‘the main barrier, I think, is the fear of asking someone to “correct” it. Taking out that human, presumably judgemental factor out of it actually made it much more friendly to people. They knew they could get their copy proofread and edited right at their own desk, without anyone being the wiser that they still have a hard time spelling certain words, or writing a non-run-on sentence, or whatever their own personal writing tic is.’ We all have our own flairs and tics which can quickly become our standard and subconscious way of writing.

Bethbot was able to keep these tics at bay without any element of awkward conversations and ill-received feedback. Bethbot is a way to keep their writers alert to their own writing bugs and learn to see them and root them out over time.

In terms of how people are actually using Bethbot, Beth only had positive examples and experiences to share. People all over HubSpot are using Bethbot, including folks in marketing, sales, social, customer support, and billing.

A key to this is the fact that Bethbot is built with the product terminology in mind. That’s the core of the experience, so as Beth said, ‘it makes sense that that’s the ground of our being as a company and as a style as well. So even though it was really built to support product copy at first, it turns out it’s super useful for all these other contexts, too. Obviously there are a few use cases, as I mentioned, that want their own additional rule sets, but for the most part the core use case is shared among all. Bethbot helps you write in the HubSpot style, voice, and tone. And that’s something everyone needs.’

Maintaining a style guide to keep it useful (and usable)

When most of us maintain our style guides it usually means reviewing and then making changes, additions, or removals to a web page, wiki or other documents. With Bethbot, it was a tad more technical and as such, it is still owned and maintained by the UX Content team. Beth has since moved on into a UX Ops role, but before that she worked to build up a team of product content designers. Then, as a team, they would routinely add words and phrases or tweak things in Bethbot. Usually, the guidance Bethbot gives you is about how to make a bit of copy better. The original engineer is still around, and gets involved when help is needed with something on the back end. And when the extensions need updating or fixing, they call on that same extension-minded engineer. 

Having the skills in-house (and the original creators) is fantastic and a reminder that for some this isn’t always the case and when people leave an organisation, so too do their skills, experience and influence. It can undo a lot of hard work so having more than one ambassador for the style guide is key to coherence and consistency in the governance of the guide.

Setting goals for a style guide

The original goal for Bethbot was to ‘automate some of the more repetitive editorial tasks of correcting people’s grammar and punctuation and so on so we could invest in more collaborative and early-stage content design on the product team.’

That was achieved and led directly to Beth and the team being able to prove the value of full-stack content design as a practice and then rapidly build out that team. Beth said ‘the ripple effect beyond product has been amazing.’ 

There have been requests for Beth to run her workshop on how to use Bethbot and other tools to write in the HubSpot style, voice, and tone, for teams all over HubSpot, and in every far-flung office they support.

Beth shared that:

It’s been particularly helpful as we start to work in more languages and regions, because a cleaner, more consistent source piece of content will be much faster and cheaper to translate and localise, too. And it helps people who are non-native English speakers brush up their skills.

Those are pretty huge wins for the outcomes of having an automated style guide bot.

Another sign of success, Beth noted, was when people stopped using Bethbot. Curious, I asked Beth to explain:

‘The best thing I hear from people is that they used to use Bethbot, but then they stopped. Because after a few months of using it, they were getting their copy right the first time. They’d learned how to follow our style guide rules without any help or proofreading, and now they just use it from time to time for a spot check.’

That’s a benefit that surpassed expectations - teams of people across the organisation that are more confident writers, which means HubSpot’s content is more consistent all over the globe.