Part 1: Welcome! Now, please memorize all of this.
I started my technical communications career in 2011. I was hired to document a new Customer Relationship Management (CRM) system for the contact center of a Fortune 50 company, and my new team had an existing style guide. For a long time, our style guide was a one-page HTML document that outlined frequently used documentation processes and even included sections of code that users could easily copy/paste directly into drafted content. This style guide version worked well for a team of 4–5 people. However, the CRM system transition project and adding several new technical writers meant we needed more extensive documentation guidelines.
A colleague and I spent several weeks transitioning the original style guide (a single HTML page) to a robust website that included internal style guidelines, general writing rules, team processes, and an HTML code cheat sheet. To ensure team adherence, we implemented a content review process. We also implemented a feedback process and routine meetings to discuss all updates and requests.
The process worked well. The writers had control over the guidelines they were held to during the writing process. Everyone had a chance to voice issues and concerns regularly. The style guide stayed relevant and updated with the latest technical communication trends. When I left the company, more than 50 people and three teams used our style guide.
Today, I work as a senior technical writer for an international software company supporting over 110 million customers worldwide. We publish content in over 35 languages and offer home and business users many products. My team publishes customer-facing content to a knowledgebase that averages about a million monthly views.
When I started, the technical writing team’s style guide was a 12-page Microsoft Word document housed on a shared drive. It worked but was cumbersome to search through. There were very few conversations about editing, updating, or adding style guide entries. It was a static document sent to new hires during initial training. It lived and died with training.
In 2017, I was tasked with transferring the style guide to a more user-friendly and globally shared space. To make things easier (and cost-effective), I wanted to use established documentation processes and a tool we already had access to for this project. We use Help & Manual to create all customer-facing product guide documentation and Jira/Confluence to track tasks and projects. We weren’t thrilled with the knowledge management system (KMS) we used then, so that was not an option.
Initially, because the style guide is strictly internal documentation, there was a push to house the new guide in Confluence. I transferred all existing style guide content to Confluence and added general writing guidelines that were missing from the original version. However, I found that Confluence did not enhance the user experience as thoroughly as we anticipated. The search functionality was often muddled with too many results, and the page view statistics were dismal.
I discussed my options with management and received the go-ahead to create a password-protected internal style guide using Help & Manual.
The Help & Manual style guide became so popular throughout the company that it was expanded to incorporate seven team-specific builds. I can quickly pull analytics for each page, document search works well, guide updates are available instantly, and user adoption has increased by 2,200%.
Part 2: What’s in a name?
As far as style guides go, ours is pretty extensive. It includes industry-specific, company-specific, and American-English-specific guidelines. Our style guide has seven team variations, and our user base continues to grow annually. It’s hosted on an internal web page that all employees can access.
A couple of years ago, my company changed the name of our flagship business product.
You can imagine my team’s reaction to such a change. Suddenly, most of our knowledgebase content was inaccurate. Hundreds of articles and thousands of screenshots had to be updated. In addition, the cloud-based equivalent of the product would have the same name (albeit with “Cloud” tacked onto the end). For a small team of five, that meant all hands on deck. We spent most of Q4 updating content to reflect the product name change.
It was three words.
Just three little words that filled Outlook calendars, project dashboards, email inboxes, and task lists. How could such a small change create so much work? We were ecstatic to finish this project just before the holiday season.
Three months later, I received an email from a copywriter on the Marketing team regarding the recent product name change.
Please consider changing “on-premises” (as opposed to “on-premise”) in our style guide because we use the phrase “on-premises management” when we refer to our products. As we know, “premise” refers to an idea or a thought, while “premises” refers to a physical location. We use the latter option to refer to our products like the management console. I’m experiencing some pushback from some other departments about this change. Thanks for taking it under consideration.
As I read the style guide request, my shoulders sank. I thought, “Oh no! How could we have missed this? How much content will we have to go back and update again?” A preliminary search of all our company websites yielded quite a few results: not enough to reopen the project, but enough to warrant adding a rule to our style guide.
Sometimes, small things like a missing “-es” can consume a department of writers and yet be insignificant to a group of developers. When many of your coworkers use English as a second (or third, or fourth) language, word variants can fall through the cracks. After all, “premise” is a real word; it’s just not the correct one to use in this context.
I emailed several departments explaining the issue. I updated the style guide, and everyone agreed to update the grammatical error in their respective documentation as necessary.
At the time, reviewing text for content quality was very much a manual process. Since I owned the style guide, it made sense for me to move into an editor role. I reviewed knowledgebase articles, online help guides, user interface strings, how-to videos, product change logs, customer emails, legal documentation, etc. The style guide is a living, breathing document, and I had to memorize a lot of it or, at the very least, be able to locate all the contextual references within it quickly.
There are 160 topics in our style guide.
I needed help.
I wanted to make the review process more efficient, but I also needed a tool to help me hold writers (across all our departments) accountable. The solution had to be easy-to-use, cost-effective, and compatible with various authoring platforms. Many products existed; however, very few style guide tools were within our budget.
At the time, we had a Grammarly Premium account. Grammarly is a writing assistant that flags your content for grammar, spelling, and vocabulary errors. It also reviews your content for clarity and identifies opportunities for you to write more concisely. We incorporated Grammarly into our day-to-day authoring and editing processes, but our internal style guide rules had to be reviewed manually.
While researching a relevant tool, I noticed that Grammarly was beta testing a new style guide feature for their Grammarly Business product. The cost to upgrade our license to Grammarly Business was surprisingly low (about $12.00/member/month), so I got management’s approval to use my team of technical writers to pilot it.
The first rule I added to our Grammarly Business ruleset was to change all instances of “on-premise” to “on-premises.”
By the end of our first month using the Grammarly Business style guide feature, I transferred over 180 rules into Grammarly. And it was working too! Writers caught errors during the authoring phase that would have typically been overlooked until editing. If a style guide entry in Grammarly was unclear or confused users, I could easily change it. Adding rules (click-to-replace and text suggestions) was easy, too.
When I started to hear “Can this be added to Grammarly?” more frequently than “Is this in the Style Guide?”, I knew our pilot was a success.
Part 3: Style guide project update and lessons learned
We’ve had several more product name changes over the last two years. Grammarly Business has been a tremendous help during those transitions. It takes only a few moments to add new or update existing Grammarly entries, and the updates are pushed to all users instantly.
Adding an in-line writing assistant to our content creators’ toolbox has ramped up company-wide style guide engagement. In the last year, since implementing Grammarly Business, we’ve received more style guide requests than we ever received in years past. Using Grammarly Business has increased content quality, cohesiveness, and accuracy across all teams.
Today, we have over 325 style guide rules in our Grammarly Business account. We manage multiple style guides and have added content creators from eight other teams to our license. Since Grammarly does much of the heavy lifting during the content review process, the process itself isn’t as long as before. I can devote more time to improving our content’s formatting and overall quality.
Our style guide project is ongoing. We continue to add new Grammarly Business users to our account weekly and were recently asked to prepare a style guide for external content creators. It is exciting to see all of our hard work pay off!