Zendesk on Zendesk: How we write KCS articles

Zendesk on Zendesk is a discussion about a specific topic and how the Zendesk Support team uses Zendesk products. Each session is hosted by a member of our Support team.

In this Zendesk on Zendesk, Stephen and Mackenzie, Self Service Specialists, explain how our content standard works and how we use Zendesk tools to write KCS articles.

See all of the Zendesk on Zendesk series discussions.  

Knowledge sharing articles 

At Zendesk, our content is maintained by various teams depending on the purpose of the articles and where they live in our help center. KCS articles are written and maintained through our knowledge-sharing program. KCS articles tend to be shorter and target specific issues a customer might be facing. They're often written with customer verbiage in mind and can help when things aren't going according to plan or when a specific use case needs to be explored in more depth. They live exclusively in the Advice and Troubleshooting section of our help center. In this article, we'll focus on how KCS articles are written and optimized for Zendesk.

*KCS® is a registered service mark of the Consortium for Service Innovation™.

The content standard

It all starts with our content standard. A content standard defines how articles should be written and provides a guideline for our writers to follow. In addition to providing some basic rules around grammar, syntax, and punctuation, the content standard helps to ensure our articles are predictable, consistent, and sound like Zendesk. Creating this unified voice helps make our content feel cohesive. We’ll explore some of the core concepts of the content standard in this article. 

Keep it consistent 

When you have multiple people all working to maintain the same Knowledge Base, variations in writing style, tone, and even regional dialects can all lead to your Help Center feeling incongruous and disjointed. One of the ways we try to combat this is by using templates on all the articles we write as part of our knowledge sharing program. At Zendesk, we utilize three templates in particular. 

• Question and Answer 

The Q&A template is used for an open forum type of article where the customer has a question, but the resolution does not require a series of steps to solve. Article Example: Can I increase the number of displayed views?

• Problem Solution

The Problem/Solution template is used when there is a specific procedure to follow to answer a question or resolve an issue. Article example: End users receiving "Couldn't authenticate you..." error when signing in

• Explore Recipe

The Explore Recipe template is used when the article is a how-to guide about building reports. Article example: Explore recipe: Count of agent interactions with tickets 

The first two templates follow a simple formula. The title introduces a problem or question which is expanded on in the first section of the article, and then a solution is provided in the last section. The recipe template introduces a use case, goes over some considerations, and then provides step by steps for building out that solution in Explore. The templates not only make our content easier for customers to understand and navigate, they also provide a simple framework for our writers as they craft new articles. 

That said, the templates don’t work for every article. Sometimes we need to create an article that walks customers through a more complex troubleshooting process. None of the above templates lend themselves well to this kind of article so we’ve recently introduced guided path articles. This breaks an article into discrete sections that can be opened and collapsed as the reader works through a process. The articles are cleaner, easier to navigate and give clear indications of where a customer is within the process. You can see this put to use in the article, General performance issues troubleshooting guide.

Templates aren’t the only thing we think about when trying to promote consistency in our content. Language is also a huge factor, especially at Zendesk. We have offices all over the world and our writers reflect the full spectrum of English speakers in all their diversity. While using regional synonyms and colloquial expressions may be more interesting, it can also be confusing for our customers. For that reason, we decided that all our articles should be written in one variation of English and we strive to use words consistently by omitting slang and idioms. Given that most of our customer base was in the United States, we decided that all our articles would be written in standard American English. 

Beautifully simple

Simplicity is one of the core principles of our content standard. As already noted, Zendesk is an international company and has customers all over the world. We want to make sure that how we say things is as simple and straightforward as possible. For this reason, we opt for simple sentences and grammatical structures whenever possible. This not only makes the information easier for native speakers to understand but dramatically improves translation success. Here are just a few of our guidelines to help promote simplicity in our written content: 

• Use present tense 

• Favor active voice over passive voice

• Keep sentences short (no longer than 23 words) 

• Use imperative mood when giving instructions 

• Omit unnecessary words 

We also try to keep our articles short and to the point and we strive to never duplicate information that is already contained somewhere else. This keeps the help center streamlined and easier to navigate. It also saves our customers the trouble of digging through walls of text to find the information most relevant to them. 

The specifics 

Unsurprisingly, our content standard is full of rules and guidelines to follow when formatting articles and deciding what should be included in them. For example, we encourage our writers to add links to other documentation in every article, use sentence structure for emphasis instead of text formatting, and use images sparingly. There are scores of other rules to help writers make decisions and craft impactful articles. 

Here’s a secret though, there are always going to be exceptions to these rules and situations where you have to bend the rules if the article is going to flow and make sense. It is exactly because the guidelines are so specific that there are so many occasions where an article may not perfectly fit all these specifications. Not every sentence is going to sound natural if it’s less than 23 words long and not every template works for every article. On these occasions, we trust our writers to make judgment calls on which rules need to be bent so the article can be as useful as possible to as many customers as possible. 

How we use Zendesk

The content standard is only one aspect of our article writing strategy. We also take full advantage of all the features and tools Zendesk offers to ensure that our articles are accessible and optimized. We’ll go over some examples below of how we utilize our own tools when working with articles.

Labels and Answer Bot

The content standard can help to ensure that our articles have the best chance of surfacing when our customers search the help center but sometimes they need a little extra help. This is where labels and Answer Bot come into play. We use labels to influence article findability and to create lists of related articles. Labels can also be used to restrict which articles Answer Bot will suggest. When overused, labels can end up having the opposite of their intended effect though so we try to keep to some general guidelines: 

• Opt for single-word labels whenever possible 
• Relevant words that are not present in the title or the body of the article should be added as labels
• Don't repeat words and don't use variation words as labels
• Try to add a label to every article you write 

These rules help to ensure that the labels don’t end up outweighing the actual content of the article itself. They also help to ensure that Answer Bot can scope articles effectively. When it comes to considerations for Answer Bot specifically, we really only have one rule: pack as much information as you can in the first 75 words. This is another reason we try to keep our articles short. Answer Bot only analyzes labels and the first 75 words of any article to decide if it should be presented to the customer so the beginning of any article needs to contain as much information as possible. 

Content review 

We have multiple people working around the clock on content for our Help Center and all that work needs to be organized and processed. This is where Team Publishing comes in handy. It allows all our writers to collaborate on new content. 

At Zendesk, we have a team of Self-Publishers who are given the role of Contributor in our Guide product. This allows them to write articles whenever they want and submit them for review. Once submitted, the article goes into a queue to be reviewed by one of our Knowledge Champions. They’ll ensure that the article adheres to the content standard and is optimized for Answer Bot. Occasionally, the article will fall outside our knowledge sharing sphere and will need to be sent off to our technical writers or another team for them to review. If it remains with the Knowledge Champion though, they can publish the article once they’re satisfied with it and give credit to the original author. This allows us to maintain a large breadth of content across all our various products without overwhelming our small team of Knowledge Champions. 

At its core, our article strategy relies on the expertise, judgment, and dedication of everyone working collaboratively to grow our help center and ensure that our customers can become Zendesk experts themselves.