Getting started with self-service – Part 4: Writing your knowledge base articles

Articles in the series

• Introduction: Elements of a self-service channel
• Part 1: Planning your self-service content project
• Part 2: Planning your self-service content structure
• Part 3: Determining what articles you need to create
• Part 4: Writing your knowledge base articles
• Part 5: Launching your help center
• Part 6: Tracking essential self-service metrics
• Part 7: Maintaining and improving your knowledge base

The previous articles in this series have described the steps involved in the build up to this step: writing your knowledge base articles. This article describes the processes and tools you can use to write your knowledge base articles and prepare them to be published when you launch your help center.

You have many options for where you actually write the articles. If you already have processes in place for creating, sharing, and reviewing documentation (you use Google Docs or Microsoft Office, for example), you can create your content outside of Guide and then move it into Guide when it’s ready to be published. Or, you can write your articles directly in Guide.

This article covers the following topics:

• Using external authoring tools
• Creating your articles in Guide
• Defining your process for reviewing and publishing your articles
• Using the Knowledge Capture app to create articles

Using external authoring tools

If you’re creating your content in an external authoring tool, you need to insert it into a new blank article that you create for that content in Guide when it’s ready to be staged or published.

The Guide editor fully supports HTML and in the Professional and Enterprise versions of Guide, you can modify the style.css file for your help center and create custom styles and formatting for the content that you add to an article. You can paste the HTML code for an article that was written outside of Guide by clicking Source Code in the Guide editor toolbar.

If you’re using the Lite version of Guide, and you want to apply formatting that is not provided by the Guide editor, you can use inline HTML formatting.

Note: At Zendesk we create our own knowledge base articles using a mix of external authoring tools, by writing them directly in Guide, and also using the Knowledge Capture app (see Using the Knowledge Capture app to create articles below). The writing tools that are used by the Zendesk product documentation team are described in How product docs are produced at Zendesk. This article also describes how we import our articles into our help center using the Zendesk API. It contains links to the code we developed that is available on Github.

Creating your articles in Guide

If you choose to create your knowledge base articles directly in Guide, you can use formatting styles provided in the Editor and never need to bother with the HTML, or you can do a mix of both WYSIWYG and HTML writing and editing to achieve the formatting you want.

Each person that creates articles in Guide needs to be an agent in your Zendesk Support account and to also have the proper permission to create articles. By default, Guide allows agents who have been given the Guide Manager permission to create and publish articles, but you can extend this to other agents as well.

To understand how user roles and permissions are set and used in the Guide, see Understanding Guide roles and privileges, Setting agent editing and publishing permissions on knowledge base articles, and Creating management permissions to define agent editing and publishing rights.

When all your contributing writers have the proper permissions to create and publish articles, they can create their articles and publish them as soon as they’re ready or based on whatever review and publishing process and schedule you’ve come up with.

How to write articles using the Guide editor is described in Creating and editing articles in the knowledge base.

Tip:

• You can create your articles directly in Guide or in an external authoring tool.
• You can copy Google Docs into new Guide articles or bring in content from an external source as text or HTML.
• You need to think about formatting and consistency (especially when bringing in HTML from an external source).
• People who create articles in Guide need to be agents in your Zendesk Support account have the proper permission to create articles.

Defining your process for reviewing and publishing your articles

As articles are completed and queued up, you should have a simple process for reviewing and then publishing them. Assuming that you’re creating your articles directly in Zendesk Guide, you can review them there and then publish them on the specific date or dates you’ve chosen for them to go live.

The new articles you create in Guide remain in draft mode until they are published. Meaning that only you and the other members of your team who have access to Guide are able to see them. As drafts, they can be reviewed and revised as needed before you publish them for your customers.

Note: In the Enterprise version of Zendesk Guide, you can mark an article as ready for review and optionally assign a team member as the reviewer. This is a feature of Team Publishing and you can read more about it in Creating new content for review. Also in Guide Enterprise, you can schedule a specific time and date for an article to be published. See Scheduling articles for publishing and unpublishing.

If you’re using an external authoring tool such as Google Docs, you should review and finalize the content before bringing it into Guide as new articles.

Don’t forget to include a review period into your schedules and it’s always best to give your reviewers a deadline date to help ensure that the reviews are completed on time.

Tip:

• Review your articles before publishing them. This is important to ensure accuracy and consistency.
• Add time into your schedules for reviewing your content.
• In Guide, you can create draft articles that can be reviewed there before publishing.
• If you’re using an external authoring tool such as Google Docs, create a process for sharing and reviewing the content before bringing it into Guide as new articles.
• In Guide Enterprise, you can assign specific people to review articles and also set a specific time and date for the articles to be automatically published.

Using the Knowledge Capture app to create articles

Another approach to creating articles, especially if members of your Support team have been tasked with creating articles, is to use the Knowledge Capture app.

The Knowledge Capture app can be used to create new articles while answering tickets using a predefined template. In other words, agents can create articles directly in Support without needing to use Guide. See Creating articles with the Knowledge Capture app.

The context here, however, is that the agents are creating new knowledge base articles related to a ticket. For example, if an agent receives a support request for a frequently asked question or support issue, she can create a knowledge base article that documents that question or issue, which is then published into the help center for all other customers to see.

You define at least one article template for use with the Knowledge Capture app (for example, a problem/solution template).

For more information, see Creating templates for the Knowledge Capture app.

How and when these articles are published is based on the agent’s Guide permissions. If they have permission to publish their own content directly to any section in your knowledge base and no review or approval is required, they can do so whenever they want. However, you’ll most likely want to set up a workflow for controlling how these articles are published. This is discussed in detail in Workflows for created and flagged articles using the Knowledge Capture app.

Creating articles in the Knowledge Capture app is a good way to expand a knowledge base with content coming directly from agents who are daily dealing with customer issues. These types of articles are usually best-suited to addressing specific support issues. For example, something goes wrong (the problem) and here are the instructions to fix it (the solution).

Tip:

• Using the Knowledge Capture app agents can easily create articles to add to your knowledge base.
• You can create article templates for your agents to use.
• Each agent’s Guide permissions determine if they can publish articles directly into your help center or must be given approval first.