Using GitHub with Help Center articles

Owned by Grant Goodman (Deactivated)
Last updated: Apr 03, 2023 by Feanil Patel
2 min read

12/5/2018: I'd recommend revisiting Zendesk's review capabilities, which allow us to assign articles for review by setting workflow states of Ready for review, Approved for publishing, and Flagged translations. This will keep commenting and review within Zendesk, as well as ensure that English updates are tracked for Spanish translation in their companion articles.

In our current configuration, the Zendesk Guide Help Centers don't have a good review and editing workflow. Most people at edX don't have access to articles before they are published, and they can't make review comments within Zendesk. Using GitHub can provide a better review and editing workflow, at some cost in clunkiness. Here is an outline of a GitHub-based workflow for creating new Zendesk Help Center articles.

  1. Create a branch in your local GitHub repository, just as you would for edits to an RTD guide.
  2. Create a new article in Zendesk Guide and leave it unpublished. Remember to set the category and section fields.
  3. Click the code button (</>) in the Zendesk Guide authoring page.
  4. Copy the HTML code into a text document, using Sublime or the text editor of your choice.
  5. Save the text document in your local GitHub repository, using your new branch. Save in the /en_us/learner_help_center or /en_us/b2b_help_center directories.
  6. Commit and push your changes from your local branch into the remote edx-documentation GitHub repository.
  7. Create a pull request, as usual, tagging subject matter experts and the doc team for review. When they review the help center article through GitHub, they will be able to see the HTML fragment that makes up the body of the Zendesk Help Center article, but won't be able to see its context in the Help Center.
  8. When you receive review comments, make the edits in your local GitHub repository, then copy and paste the HTML fragment into the code view of the article in Zendesk Guide.
  9. Publish the article in Zendesk Guide.
  10. Merge your branch into master in GitHub, then delete the branch. This step doesn't matter much, since we'll be using what's published in Zendesk Guide as the master version, but it will help keep the edx-documentation repository more tidy if there aren't unneeded branches hanging around.


Filter by label

There are no items with the selected labels at this time.