Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 35 Next »

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

Note: The edX Learner Guide is the only help content maintained outside of Read the Docs in Zendesk. 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.

The following procedures can be used when:

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 (or category or section). 
  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. 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.
  7. Verify and test the article in both the current and in-development themes. Note that testing the documentation is required. 
    1. Test the current theme: On the article editor page, select Show in Help Center to launch the article in the current theme; this shows how the article will be formatted and appear when published and live in the help center.
    2. Test the in-development theme: On the left of the screen, select Customize design. Under Custom themes, select View theme. This will load the in-development theme on any currently opened help articles, as well as any you open after loading the theme. Note that this does not publish the theme, or change any formatting to the currently live help center site.
      Note: 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.
  8. When the styling and content have been tested and revised if necessary, 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 using the search field, and/or by filtering to control the articles that you see.
  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 Show in Help Center. 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. Note that testing the documentation is required.
  6. Select Save to save your changes. This will set the article workflow at Work in Progress. The unchanged article is live, and the changes to the article are not yet visible.
  7. 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 software. 

  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 using the search field, and/or by filtering to control the articles that you see.
  4. Copy the article title and article content. You will be pasting this into a new article, as today Zendesk does not offer a way to more formally control versions. 
  5. In the upper left corner, select Add, then select Article (or category or section). 
  6. Paste in the article title, and add the word DRAFT at the end of the title. Paste in the article contents. For information on formatting, see Style guidelines for help articles in Guide.
  7. Select Save to save your changes.
  8. Verify and test the article by selecting Show in Help Center. This launches the article in the current theme and shows how the article will appears once it is 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. Note that testing the documentation is required.
  9. When the feature releases and you want to publish the help article, locate the current article via title, which will show both the live and draft versions.
  10. Open the draft article, and copy all of the article contents. Overwrite the live article by pasting the draft content into the live article.
  11. Select Save to save your changes. This will set the article workflow at Work in Progress. The unchanged article is live, and the changes to the article are not yet visible.
  12. Verify and test the article by selecting Show in Help Center. Fix any formatting issues, then save and preview the article again, until you are satisfied with the output. Note that saving to a live article publishes the updates automatically, so you need to fix formatting issues immediately.
  13. Delete the draft when you have updated and the live article and no longer need it.

To publish a draft article (or category or section)

  1. Log in to Zendesk.
  2. On the left, select Manage articles. 
  3. Under Lists, select Drafts. 
  4. Locate your draft article (or category or section). You can do this by using the search field, and/or by filtering to control the articles that you see.
  5. Verify and test the article by selecting Show in Help Center. This launches the article in the current theme and shows how the article will appear when published and 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. Note that testing the documentation is required.
  6.  Once 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 when you first created the draft.

Additional Information

  • No labels