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

Available on all Suite plans

Articles in the series

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 Knowledge 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.

Note: At Zendesk we create our own knowledge base articles using a mix of external authoring tools and by writing them directly in Guide. The writing tools 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 must be an agent in your Zendesk Support account and 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 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. This means 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 Knowledge 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 section of the context panel. Depending on your settings, agents can create help center articles from a blank article or any pre-defined templates that are available. See Creating and requesting articles in Knowledge.