Creating and Updating Documentation - Zendesk Guide

Owned by Deb Chatigny (Deactivated)
Last updated: Apr 03, 2023 by Feanil Patel
5 min read

The following steps detail the process of creating and updating edX Help Center documentation in Zendesk Guide.

Note: The majority of technical documentation is authored and maintained via Sphinx and Read the Docs. See the table at 3. Locate and Edit Documentation for file locations for various documentation products.

Before you begin, ensure that you have the right permissions to author in Zendesk Guide.

Procedures:

To create a new help center article

NOTE: Before creating a new article, always check to see whether there is an existing article addressing the same or similar issue. If an existing article exists, instead of unpublishing the existing article and publishing your new article, you should have the new article reviewed then, when it is ready to publish, paste new content into the existing article. Doing so ensures that any metrics on the existing article are not lost and Answerbot use is not disrupted.

  1. Log in to Zendesk.
  2. In the upper right corner, select  , then select Guide. The Themes page appears.
  3. In the upper left corner, select Add, then select Article.
  4. In the left hand pane, enter the article title and content. Use the appropriate formatting options for the article type. For information on formatting, see Style guidelines for help articles in Guide, in the edX brand. You must be logged in to Zendesk to view this article.
  5. In the right hand pane, enter the following:
    1. Under Publish in section, select the category and section that the article will appear in. 
    2.  Deselect the checkbox for Open for comments. Note: This is selected by default. This allows commenting on articles that we are presently not staffed to moderate. 
    3. If desired, select the checkbox for Promote article. Promoted articles appear at the top of any menus and article lists and typically address common questions. Promoting articles helps surface content that may otherwise be lost in alphabetical lists or other section hierarchies.
  6. Select Save. This saves but does not publish your article, and changes the state to Work in Progress.
  7. Verify and test the article by selecting Preview in the righthand column. This launches the article in the current theme and shows how the article appears live in the help center. To ensure formatting consistency, testing the documentation is required. 
  8. When the styling and content have been tested, select the dropdown arrow next to Save and select Publish.
    This automatically publishes the article and adds it to the live help center in the category and section that you set.

To update an existing help center article and publish immediately

There may be times when you need to update an existing article and publish the changes immediately - for instance, if you find a typo or become aware of an error in a live article that you want to fix. 

  1. Log in to Zendesk. 
  2. On the left, select Manage articles. 
  3. Locate the help center article that needs updating. You can do this by entering words from the article title in the search field, using filters in the Filters dropdown, and sorting by selecting an article state (Published, Ready for review, Work in progress, etc.) from the lefthand column.
  4. Make the needed updates. For information on formatting, see Style guidelines for help articles in Guide.
  5. Verify and test the article by selecting Preview in the righthand column. This launches the article in the current theme and shows how the article appears live in the help center.
    Note that article styling, especially if you've copied in content from another source or document, will not always display as expected. You may have to select Source code (), located in the editor toolbar, to adjust the formatting, or reformat the text within the editor window. To ensure consistent formatting, testing the documentation is required.
  6. Select Save to save your changes. This will set the article workflow as Work in Progress. The current and unchanged article is live, and the changes to the article are not yet visible.
  7. A Flag translations dialog box appears. Select the toggle to flag the article, so that it can be added to the Flagged translations list (currently to track needed Spanish article updates) and marked as out of sync with the English source help article.
  8. Select the dropdown arrow next to Save and select Publish to publish your changes.

To update an existing help center article with future changes

There may be times when you need to update an existing article but do not want to publish the changes immediately - for instance, if you are documenting a change to an existing feature or option, and need to wait to publish the article updates until the changes are live in the course or platform. 

  1. Log in to Zendesk. 
  2. On the left, select Manage articles. 
  3. Locate the help center article that needs updating. You can do this by entering words from the article title in the search field, using filters in the Filters dropdown, and sorting by selecting an article state (Published, Ready for review, Work in progress, etc.) from the lefthand column.
  4. Make the needed updates. For information on formatting, see Style guidelines for help articles in Guide.
  5. Verify and test the article by selecting Preview in the righthand column. This launches the article in the current theme and shows how the article appears live in the help center.  Note that testing the documentation is required.
  6. Select Save to save your changes and update the article status in Zendesk to Work in Progress. The current and unchanged article is live, and the changes to the article are not yet visible.
  7. When the feature releases and you want to publish the help article, locate the current article via title. You can also find the article via the Work in Progress list.
  8. Select the dropdown arrow next to Save and select Publish to publish your changes.

To display an article or section in multiple sections or categories

While Zendesk Guide has this capability on their roadmap for Q3 (early 2019), Guide does not yet include a native way to display articles in more than one section, or to display sections in more than one category. However, the Zendesk community has created code to allow for this option. See this Zendesk Guide help article for code on how to configure this.

Additional Information