When you are authoring or reviewing help center articles, ensure you check the following before approving, reassigning, or publishing the article. See the style guidelines article in Zendesk Guide for details on specific styles and formatting guidelines.
Article settings
- Ensure that the Open for comments and Promote article checkboxes are deselected for the article.
Article body
- Is spelling and grammar accurate, appropriate, and succinct?
- Are paragraph styles applied to all body paragraphs?
- Is Heading 3 used to introduce procedures or lists? Is Heading 4 used when there are subsections within any Heading 3 content?
- Are numbered and bulleted lists used where needed?
- Is the note style applied to any notes?
Images
- Is the image really necessary? If not, don't include it.
- Search our centralized image repository at edx-documentation/en_us/shared/images before creating new images. If the image you want does not exist in the repo, create a screenshot following our standards, then add the image to the repo via a PR.
- Are images clear, and is text in the image readable?
- Have you properly cropped the image to exclude extraneous detail?
- Do images include alt text? Zendesk automatically generates alt text based on the file name of the image you upload or drag/drop into the article. Replace the filename with useful descriptive alt-text.
- Do images have a 1 pixel black border?
Hyperlinks
- Are hyperlinks embedded in text, as opposed to being pasted into the article?
- Do this: edx
- Don't do this: https://edx.org
- Are hyperlinks set to open in a new window?
- Have you launched all hyperlinks to ensure they launch pages and do not produce 404 errors?
- Ensure hyperlink text describes the link, and is not "click here".
- Within the article editor, ensure hyperlink URLs to other help center articles do not include the article name. This will prevent future 404 errors if we change the article name.
Article Hierarchy
If you have added a new article to a section, it will automatically appear towards the top of the section, directly after promoted articles. If the logical order of the article is not at the top of the section, navigate to the Arrange Content page, find the category and section the article is in, and move the article to the desired position by dragging it into place.
Preview the Article
Preview the article to ensure that the formatting appears as expected. To do this:
- Preview a help center article in the current theme.
- Ensure that images, lists, headings, notes, tables, and other formatting displays as expected.
To view articles in a different theme
From time to time, we will update the theme with new branding and colors. To view an article in a theme other than the currently applied (live) theme, do the following:
- Open the article that you want to preview in the current theme, so that it is loaded in a browser window.
- In Guide, on the left hand side of the page, select Customize Design. The Themes page appears.
- Under Custom Themes, hover over the theme you want to apply to your preview and select View theme.
This will load the draft theme in all article tabs that you have open. - Select the browser tab that has the preview help article. It should now display in the draft theme so that you can verify formatting and styling.