Setting up your knowledge base

How to configure your Help Center for success

  • Organizing knowledge base content

    You can organize your knowledge base content into categories and sections and manage the order of those categories and sections.

    You must be a Guide Manager to add and edit sections and categories.

    Adding a category to your knowledge base

    Categories are the top-level organizing containers of the Help Center and at least one must exist. Categories contain sections. If you have only one category in your Help Center, then the category itself is hidden to end-users, and they see only the sections in your Help Center.

    For more information, see About the Help Center knowledge base structure.

    To add a category

    1. In Help Center or Guide Admin, click Add in the top menu bar, then select Category.

      Add a new category

    2. Enter a Name and optional Description for your category.
    3. (Guide Enterprise) In the sidebar, if you have multiple category templates in your live theme, click the Template menu, then select a template.

      If you do not select an alternate template, the default category template will be applied.

      Select a template

    4. In the sidebar, ensure the correct Source language is selected.
    5. Click Add.

    The category is created. Remember, if you have only one category, then the category itself is hidden to end-users, and they see only the sections that are in your Help Center.

    For information about how you can display a section in multiple categories, see Displaying an article or section in multiple sections or categories in our Support tech notes.

    Adding a section to your knowledge base

    Sections are collections of related articles. To add a section, you must have at least one category to act as its parent container.

    • On Guide Lite and Professional, each section must be child of a category.
    • On Guide Enterprise, a section can be a child of a category or a section.

    Permissions for viewing and managing articles in a section are set at the article level, not the section level.

    If visibility for all the articles in a section is internal (Professional and Enterprise only), then the section will not be visible to end-users, but if one article in an internal section is visible to any end-users, then the section will become visible as well.

    To add a section

    1. In Help Center or Guide Admin, click Add in the top menu bar, then select Section.

      Add a new section

    2. Enter a Name and optional Description for your section.
    3. (Guide Professional and Enterprise) Ensure the correct Source language is selected if you support multiple languages.
    4. Under Order articles by, select an option for how you’d like articles to appear in this section.

      If you select to manually order of articles, see Manually changing the order of articles to change the order of your articles.

    5. Under Hierarchy, click in the field, then select where you’d like this section to appear in your Help Center.

      On Guide Lite and Professional, you must select a category as the parent for this section. Sections cannot contain sections.

      On Guide Enterprise, you can select a category or a section as the parent for this section. You can nest sections in sections for a maximum of five section levels, with up to 20 sections in a section.

    6. (Guide Enterprise) If you have multiple section templates in your live theme, click the Template menu, then select a template.

      If you do not select an alternate template, the default section template will be applied.

    7. Click Add.

      The section is created. Remember, if you have only one category, then the category itself is hidden to end-users, and users see only the sections that are in your Help Center.

    Deleting categories and sections

    When you delete a category, all the sections contained in the category are also deleted, and all the articles contained the sections are archived.

    When you delete a section, all the articles contained in the section are archived.

    To delete a category or section

    1. Do one of the following to edit the category or section you want to delete:

      • In Help Center, navigate to the category or section you want to delete, then click Edit section in the top menu bar.

        Edit section

      • In Guide Admin, click the Arrange content (Arrange content icon) icon in the sidebar and drill down to the category or section you want to delete. Click the options menu at the end of the section title, then select Edit category or Edit section.

        Arrange articles

    2. Click Delete in the bottom of the sidebar.
    3. Confirm that you want to delete the category or section.

      Alternatively, to delete a category or section, you can click Articles > Arrange articles, then click the name of the category or section you want to delete (you’ll have to expand a category to see its sections).

      In the edit page, click Delete in the bottom of the sidebar.

      You cannot recover deleted categories or sections. Any articles contained in a deleted section are archived and you can restore archived articles to another section if you need to.

    Working with category and section drafts

    If you create a category or section that is a work in progress, and want to restrict who can access it, you can mark it as a draft. Marking a category or section as a draft applies the draft status to any elements within it.

    The steps for marking a newly-created category or section as a draft are slightly different than those for marking an existing category as a draft.

    To mark a newly-created category or section as a draft

    1. Create and save a new section or category, as described in Adding a category to your knowledge base or Adding a section to your knowledge base.

      The section or category is created and remains open for editing.

    2. Click the Mark as draft option in the sidebar.

      Mark as draft

    3. Click Update at the top of the page.

    To mark an existing category or section as a draft

    1. Open the category or section in edit mode, as described in Editing categories and sections.
    2. Click the Mark as draft option in the sidebar.
    3. Click Update at the top of the page.

    Categories and sections marked as drafts are not viewable by end-users, and can only be accessed by Guide Managers.

    To determine whether a category or section is marked as a draft

    • Open the category or section in edit mode, as described in Editing categories and sections.
    • An existing category or section in draft mode section in draft mode is indicated by the Draft label at the top of the edit page:

    Section in draft category

    • A new section added to a category in draft mode displays a banner at the top of the page:

    Draft_category

    When the category is published, the section is no longer in draft mode, and the banner is removed. However, if the section is manually marked as draft, it will remain in draft mode until the marker is removed.

  • Moving and reordering sections and articles

    As your Help Center grows, you may find that you need to move existing sections from one category to another, or move articles from one section to another.

    Moving a section to a different category

    You can to move an existing section from one category to another.

    There are two ways to do this. You can either navigate to the section in Help Center and edit it or you can navigate to the section in Guide Admin and move it.

    To move a section to a different category in Help Center

    1. In Help Center, navigate to the section you want to move, then click Edit section in the top menu bar.

      Edit section button

    2. Under Hierarchy in the sidebar, click the name of the current category.
    3. Select a new category for the section, then click Select.

      You can search for or navigate to the category. All of your categories might not appear in the window.

    4. In Edit section, click Update.

    To move a section to a different category in Guide Admin

    1. In Guide Admin, click the Arrange content (Arrange content icon) icon in the sidebar.
    2. In Arrange articles, drill down to the section you want to move.
    3. Click the options menu at the end of the section title, then select Move to.

      Arrange articles option menu

    4. Select a new category for the section.

      You can search for or navigate to the category. All of your categories might not appear in the window.

    5. Click Move.

    Moving an article to a different section

    You can move an existing article from one section to another.

    There are two ways to do this. You can either navigate to the article in Help Center and edit it or you can navigate to the article in Guide Admin and move it.

    To move an article to a different section in Help Center

    1. In Help Center, navigate to the articles you want to move, then click Edit article in the top menu bar.

      Edit article

    2. (Guide Enterprise only) Click Article settings.
    3. Under Publish in section, click the name of the current section.
    4. Select a new section for the article, then click Ok.

      You can search for or navigate to the section. All of your categories might not appear in the window.

    5. In Edit article, click Update.

    To move an article to a different section in Guide Admin

    1. In Guide Admin, click the Arrange content Arrange content icon) icon in the sidebar.
    2. In Arrange articles, drill down to the article you want to move.
    3. Click the options menu at the end of the article title, then select Move to.

      Arrange articles options menu

    4. Select a new section for the article.

      You can search for or navigate to the section. All of your categories might not appear in the window.

    5. Click Move

    The article is moved to the new section.

  • Viewing and restoring archived articles

    You can access a complete list of your archived articles. You can restore an article from your archived list if you want to make it available again in your knowledge base.

    You must be a Guide Manager to view and restore archived articles. For information about archiving an article, see Archiving an article to remove it from your knowledge base.

    Viewing the archived articles list

    You can access a complete list of your archived articles. An archived article remains in your list unless you delete it.

    You must be a Guide Manager to view archived articles.

    To view a list of archived articles

    1. In Guide, click the Manage articles (Manage articles) icon in the sidebar.

      The Lists tab opens by default.

    2. Click Archived articles.

      Archived articles

      A list of your archived articles appears. You can add filters to view a subset of all your archived articles.

    Restoring an archived article

    You can restore an archived article if you want to make it available again in your knowledge base. You cannot disable the ability to restore articles. If you need to restore multiple articles at once, see Updating knowledge base articles in bulk.

    You must be a Guide Manager to restore archived articles.

    To restore an archived article

    1. In Guide, click the Manage articles (Manage articles) icon in the sidebar.

      The Lists tab opens by default.

    2. Click Archived articles.

      A list of your archived articles appears.

    3. Find and select an archived article from your list.

      You can browse, search, or add a filter to find a specific article.

    4. In the archived article, click Restore.

      The article is restored as a draft or work in progress, depending on your plan type, in the section where it was previously published. If the section no longer exists, you are prompted to select a new section.

    5. When you are ready to publish the article, click the drop-down arrow on the Save button, then select Publish now.

  • Updating articles in bulk

    From an articles list, you can update one or more articles at once using the bulk actions options. For example, you can publish a batch of articles at once or add a labels to several articles.

    You can make the following updates using bulk actions:

    • Archive or restore articles
    • Delete articles
    • Change author
    • Open or close for comments
    • (Guide Professional and Enterprise) Change labels on articles
    • (Guide Professional and Enterprise) Change user permissions
    • (Guide Enterprise only) Assign or unassign articles
    • (Guide Enterprise only) Submit articles for review
    • (Guide Enterprise only) Submit articles for approval
    • (Guide Enterprise only) Schedule articles for publishing
    • (Guide Enterprise only) Schedule articles for unpublishing
    • (Guide Enterprise only) Verify or unverify articles
    • (Guide Enterprise only) Change article owner
    • (Guide Enterprise only) Publish or unpublish articles

    To update articles in bulk

    1. In Guide, click the Manage articles (Manage articles) icon in the sidebar.
    2. Find the articles you want to update by browsing, searching, or using a new or existing articles list.
    3. Select one or more articles to update.

      You can select a maximum of 30 articles at a time. To select 30 items at once, click the check box beside the number of results at the top.

      Select all

    4. Click one of the bulk actions menus at the bottom, then select an option.

      The bulk actions that are available depend on your plan.

      Actions select

    5. Click to confirm that you’d like to perform the action, or enter your update, if necessary.

      Some actions require an additional step:

      • For assign, select a team member and enter a note, then click Assign.
      • For change labels, select or deselect labels to add or remove them or enter a new label, then click Change.

      For more information, see Updating article labels in bulk.

      • For restore, select a section for the article, then click Restore.
      • For scheduled publishing and unpublishing, click to create a schedule to publish or unpublish an article. Select a date, time, and time zone, then click Schedule.

      You can select both check boxes to create a publish schedule and unpublish schedule in one action.

      The action is applied to all the selected articles.

  • Using labels on your articles

    Labels are a single word or a multiple word phrase you can add to the default language version of a specific article in Help Center. You can use labels to influence article search relevance, to influence Answer Bot results (if you are using Answer Bot), or to create a list of related articles based on labels.

    You can add and remove labels on individual articles or you can change labels on multiple articles at once. You must have Guide Professional or Enterprise to use article labels.

    Adding and removing labels on individual articles

    Labels are a single word or a multiple word phrase you can add to the default language version of an article in Help Center. You can add articles labels for multiple purposes, including to influence search and Answer Bot results or to create article lists (see Understanding why to use labels).

    You can add and remove labels on individual articles or you can change labels in bulk for multiple articles at once.

    To add or remove labels to an article

    1. In Help Center or Guide, navigate to the article where you want to change labels, then click Edit article in the top menu bar.

    2. (Guide Enterprise only) If you are on Guide Enterprise, click Article settings. This step is not necessary on Guide Professional.

    3. In Labels in the right sidebar, start typing the label you want to add, then select Add as new label or select the matching label, if it exists.

      You might have to scroll down to see labels. See Best practices for adding labels below.

      Article labels

      Labels live on the default language article and not on translations of the article. If you have translations, you can add labels in multiple languages to the default article.

    4. Add multiple labels as needed.

    5. If you need to remove a label, click the x beside the label name.

    6. Click Save.

    You must manage labels on each individual article or using the API. There is no global management for article labels.

    Changing article labels in bulk on multiple articles

    You can add or remove labels to on multiple articles at once.

    1. In Guide, click the Manage articles (Manage articles) icon in the sidebar.

    2. Find the articles you want to update by browsing, searching, or using a new or existing articles list.

    3. Select one or more articles to change labels.

      You can select a maximum of 30 articles at a time.

      Article bulk actions

    4. Click the Article settings menu at the bottom, then select Change labels.

    5. Do any of the following:

      • Add a new label: Enter the label, then click Add as a new label.

      Bulk label add new

      • Add an existing label: Search or browse to find the labels you want to add, then select any empty checkbox or any checkbox with a minus.

      The minus sign (minus) indicates that the label appears on some but not all of the selected articles. When you select it, it changes to a checkmark (checkmark), indicating that it will be added to any selected article that doesn’t already have that label.

      You can select multiple labels to add to the selected articles.

      Select existing

      • Remove an existing label: Search or browse to find the labels you want to remove, then deselect one or more labels.

      The checkmark (checkmark) indicates that the label appears on all of the selected articles. The minus sign (minus) indicates that the label appears on some but not all of the selected articles. When you select a checkbox with a minus sign, it changes to a checkmark.; click it again to deselect the checkbox.

      You can select multiple labels to add to the selected articles.

      Remove labels

    6. Click Change.

      The label changes are applied to the selected articles.

    Understanding why to use labels

    Labels have the following uses and impacts:

    • Influence article search relevance

      Adding labels can make your articles more search friendly. They are not designed to be used for fine-grained control of ranking. For example, if I have two articles about making waffles, one with the word “temperature” in the body of the article, one with the label “temperature”, the labeled article will be ranked higher if a user searches for the word “temperature”.

      Labels are indexed for search with a bit less weight than the article title, but multiple labels with similar words can outweigh the title and body of the article. Use labels carefully as you can significantly impact the relevance of your search results and usefulness. If you are considering using labels to impact search relevance, consider that efforts to do so could end up with inferior ranking performance for your users. The best way to have your article perform well in search is to create a short and focused article, where the title and body include keywords and clearly connect to each other.

      To learn more about search, see How end-user search works in Help Center.

    • Influence Answer Bot results

      Answer Bot uses labels to influence the results it shows. It allows you to define a whitelist of articles that are allowed to be used when looking for relevant matching results. You are able to add up to ten labels that serve as an OR filter, allowing you to expand the whitelist to any articles containing any of the defined labels.

      To learn more about Answer Bot, see About Answer Bot.

    • Create article lists

      Article lists enable you to get an overview of all your published and unpublished knowledge base content, and then refine that view by using search and applying filters to build article lists. For example, you can find articles that have a specific article label, such as out-of-date.

      To learn more about article lists, see Creating article lists to different views of your knowledge base content.

    Best practices for adding labels

    Labels can help boost the search relevance of an article. However, you should use labels carefully and sparingly. It’s more important to make sure the article title and body contain the relevant keywords.

    • Use single word labels where possible, instead of multi-word phrases

      It is possible to add labels as single words or as multiple words or phrases. In general, it’s more efficient to use single word labels. If you add a multi-word label, the search engine breaks it into individual words to perform the search. For example, if you have a label of “late delivery,” it gets broken down into “late” and “delivery” for search.

      Avoid using long phrases as labels to boost an article’s ranking with respect to a query. For example, “Can I return something I ordered online to my local store.” Instead, you should modify the article’s title or content to make it literally relevant to the query.

    • Do not include variations of the same word, including different tenses or plural forms

      You do not need to include multiple labels for variations of a word. For example you do not need a label for “return” and “returns” or “update” and “updated.” Search stemming allows different forms of the same word to match. In particular, the singular and plural forms of a word will generally match.

    • Use a limited number of labels, instead of overloading an article with labels

      Use labels sparingly. Adding lots of labels might actually diminish any matches on labels. This is because it is assumed that matches with a fewer number of labels beats matches with more labels. And too many labels might outweigh the relevance of the title and body.

      For example, if article 1 has the labels “car,” “automobile,” and “transport” and article 2 has only the label “car,” all other things equal, if the end-user searches for “car,” the article that has only the label “car” will rank higher. That is because, as a general principle, an article that is about one specific thing is more relevant than an article about many things, when a user is looking for that one specific thing.

      The number of labels for search is limited to 200. The search engine will use the first 200 labels and ignore any additional labels.

      Your best bet is to look at the top ranked search queries and make sure that they exist in either (but not both) the title or the labels. You don’t give content an extra boost if you match a term across the title, body, labels, and comments.

    Using the Help Center API to filter articles by labels

    There are two ways you can filter articles by labels using the Help Center API:

    • Article: /api/v2/help_center/en-us/articles.json?label_names=foo​
    • Search: /api/v2/help_center/en-us/articles/search.json?label_names=foo

    These two endpoints behave differently and will return different article results. They are programmatically different and query different data sources for their results.

  • Importing Google Docs as articles

    You can import Google Docs into your Guide knowledge base. You can import up to 100 docs at a time. This is a great way to add new content or migrate existing content to your knowledge base.

    When you import a Google doc, there is no connection between the new article and the original Google Doc; the article is not synced with the Google Doc. You cannot export articles from your knowledge base to Google Docs.

    You must be a Guide Manager to connect to a Google Drive and import Google Docs.

    To import a Google Doc

    1. In Guide, click the Arrange content (icon_arrange_content) icon in the sidebar, then click Import articles.

    2. Click Connect to sign in to your Google account, if you are not already signed in.

      If you have not yet connected Guide to your Google Drive account, clicking Connect takes you through the process of signing in to your account and granting Zendesk Guide.

      Google Docs importer

    3. Click Next.

    4. In Select documents, click Open file picker.

      You will see all the folders and files that you have access to.

      Google Docs file picker

      Use the options in the upper-right to toggle between grid and list view or to sort your files.

    5. Search or navigate to the file(s) you want to import, then click Select.

      You can select up to 100 files to import at a time.

      The file appears in the Import Articles admin page. You can click Redo document selection if you need to choose a different file.

    6. Click Next.

    7. In Place documents, click Select section to choose a section in your Help Center for this article.

      The articles will not be published when they are imported. Docs are imported as draft articles (Lite and Professional) or work in progress articles (Enterprise).

    8. Click Next.

    9. In Start import, click Start import.

      Don’t close the window while the importer runs. The time it takes depends on how many docs you are importing.

      Your docs will be imported as draft articles (Lite and Professional) or work in progress articles (Enterprise).

    10. When the import finishes, click Have a look to go to Arrange articles and find your articles or click Start a new import to import more Google docs.

      There is no connection between the resulting new articles and the original Google Docs; the articles are not synced with the Google Docs.

      To access your articles later, you can find them in your list of drafts or your list of work in progress (Enterprise).