As a member of the QA team, you will be working closely with another department to create Zendesk Help Center content that is usable for them. The department manager and/or assistant manager should be your key point of contact as you develop and edit articles.
The purpose of managing and creating Zendesk articles is to:
- Document repeatable processes
- Provide reference material on job tasks
- Assist in educating new employees
- Ensure company-wide consistency
Writing Style
To maintain a consistent look and feel in the Help Center, we have certain guidelines for you to follow as you draft and review articles.
Tone
Zendesk articles are only for internal use. Because of this, we can adopt a friendly, conversational tone. If you find room for light humor in the article, feel free to include that as well.
As long as the tone doesn't detract from the article's overall purpose, you have the freedom to express yourself in whichever way you choose.
Note: Figure out who the “you” is in your article and then address them like you’re speaking face-to-face. This will draw the reader into the article. It will also force you out of using passive sentence constructions.
Titles & Headers
Most readers will skim an article to find the information they're looking for. We can help them out by making our titles and headers descriptive and interesting. Consider starting with a verb; it helps you to focus your content on actionable information.
Example: Managing the Phone in Zendesk sounds more descriptive than Zendesk Phones.
Headings help you to organize information in an article. There are four levels of headings available in Zendesk. Heading 1 is only ever used in the title of the article. Because this autoformats when you create a new article, you will never need to make a Heading 1 yourself.
Headings 2 and 3 are the heading styles you should use inside an article most often. Heading 2 should be written in title case while Heading 3 should be written in sentence case. Before each new section beginning with a Heading 2, you should insert an extra line to clearly communicate the division of information.
Heading 4 is used in rare cases when you've written a long article that needs further division of information.
Note: Create a cushion between headings using body text. Writing in headings one after another looks sloppy.
Body Text
Other than titles and headings, it's important that you write understandable body text. Body text is what comes between headers and will be the bulk of your writing. As such, aim for brevity without sacrificing meaning.
- Sentences should be short, meaning no more than two clauses
- Paragraphs should be no longer than four sentences
Consider using bulleted, dashed, or numbered lists to create a visual hierarchy of information. We typically use dashed lists to introduce list items while we use bullet points to introduce examples.
In addition to conciseness, aim for specificity and detail in your writing. Because many of these articles explain how to perform certain job tasks, use any resources you can to make the explanations easy to follow. You can also include screenshots, photos, or screen recordings to help the reader understand. Ask yourself, "Am I accurately explaining the what, where, when, and why of this process?"
Example: The sentence, "Make sure you click on the right button for exiting the window," would be easier to understand if it was written like this: "Exit the window by clicking "Exit" in the upper right corner." Additionally, you could include a screenshot highlighting where to click.
Italics vs. Quotation Marks
When you are referring to a hyperlinked item that the reader is meant to click or locate, use quotation marks around the item's text. In line with the corporate style guide, you may use italics to emphasize vitally important words in a sentence. Similarly, you may use italics instead of quotation marks when you introduce a specific word or expression that you are referring to in the sentence.
Example: At the bottom of the page, click "Continue" to advance to the final exam. In the final exam, pay attention to instances of the word Important. It indicates questions that are worth double the points.
Visual Style
Make articles visually digestible and understandable. No one wants to read walls of text. Remember, the employee will usually skim these articles. We want to make it easy for them to find what they need. Create frequent breaks in the article through highlighted boxes, pictures, and videos.
Highlighted Boxes
Within each article, you can add "Note," "Example," or "Important" boxes. Each of these boxes color and emphasize a particular part of the text.
To add a highlighted box, you will need to go into the source code and locate the text you want in the box. Each of the boxes below shows the code needed.
Note: To insert, click Source code and add the following code around the paragraph you want to emphasize. Don't forget to indent the paragraph. <div class="note-box"> </div>
Example: To insert, click Source code and add the following code around the paragraph you want to emphasize. Don't forget to indent the paragraph. <div class="example-box"> </div>
Important: To insert, click Source code and add the following code around the paragraph you want to emphasize. Don't forget to indent the paragraph. <div class="important-box"> </div>
Essentially, you would put the code before and after the text you want to be highlighted, as shown:
Pictures
Pictures are a way for you to visually emphasize the information you're trying to convey. In some instances, screenshots and animated GIFs may convey what you're trying to say better than words can.
Animated GIFs
Animated GIFs are short looped video clips. In the Help Center, we use these to depict a brief screen recording using software called LICEcap. Once you've downloaded this software, you can use LICEcap to record brief screen recordings on your computer.
The .gif file that is created from your screen recording can be added into Zendesk the same way you would insert an image.
The Use of Tables
Zendesk does not have a feature that allows text to wrap around images. However, we can trick the system using tables.
To do this, go up to the table icon and insert a table with at least 2 columns, and as many rows as you need. On the new table, click inside a row or column. Then click on the table icon again and click "Table Properties." In the box titled "Border" change the number to 0. This makes the lines of the table invisible in the published version.
You can then add pictures on one side, and text on the other.
Embedded Videos
You may want to embed videos in an article to showcase a screen recording you made or a helpful tutorial from YouTube. To embed a video from another webpage, you simply click the video icon in the article editing toolbar and insert the link.
To insert videos that you make using Loom, follow the steps inside the article Creating Screen Recordings in Loom.
Settings
To make the article viewable to employees company-wide, there are a couple of settings you need to change prior to publishing. These are accessible on the right side of the screen.
- Managed by: Admins
- Visible to: Everyone
- Publish in section: select the appropriate category and section inside the Help Center
- Open for comments: check off
Once you've changed these settings, you can click the drop-down arrow next to "Save" in the upper right corner of the screen. Select "Publish" to make the article viewable in the Help Center.
Review Process
Good processes and writing is never produced in isolation. Rely on your peers to edit and proofread your Zendesk articles. The following steps generally outline what happens when a new article is finished:
- QA writer recruits a reviewer from the QA department to run a functionality check.
- QA reviewer makes changes and shares feedback with the QA writer.
- QA writer recruits a second reviewer from the QA department.
- Second QA reviewer makes changes and shares feedback with the QA writer.
- QA writer shares the article with the appropriate department and gets any final suggestions.
Comments
1 comment
Very good! Thank you for this article!
Please sign in to leave a comment.