This guide will help you write articles for our new knowledge base. The guide covers two main aspects;
Part 1 - (Heading 2) Content Template
In this next section we are going to lay out a basic template for what needs to be included as a bare minimum in every article. Some products and ideas may require additional sections or a slightly different approach, but it's important we include the following as standard.
(Introduction) In this article we are going to learn about 'X'. 'X' is useful when doing 'Y' on the platform. For more information, you may want to check out articles 'Z' and 'Z'.
Here's what we'll cover in this article;
Make sure when writing your own articles to include 'Anchor links' as we can see above. You can create 'Anchor links' (links to other sections of the same article) by clicking on the 'link' button in the editing toolbar at the top of the page.
1. Highlight target text and click the 'link icon'
Highlight the text that you want to act as a hyperlink to another section within the article.
2. Find the heading you want to link to
Under the 'Heading' tab within the 'Link' modal, find the section to which you want to link. Press 'Link' once you've found the correct heading. You should now be able to create 'anchor links' to other areas within the same article.
(Heading 2) - Understanding 'X'
In this section, you should give a user an idea of what X does on the platform. Here are some questions that might help you figure out what needs to go in this section;
- What is the basic premise of 'X'?
- What are the end goals of using 'X'?
- (Organiser experience - which step is 'X' a part of? If necessary, link to another explanatory article)
- Who can use 'X'?
- What else might it be useful to understand before tackling 'X'?
For example, if you were talking about Speed Networking sessions you might writing something similar to the below;
- Speed Networking allows users to have meetings with other users on the platform quickly and efficiently.
- Speed Networking has to be enabled by event organisers on individual events, but when enabled, all users can participate.
- Speed Networking is conducted on Grip by creating a Speed Networking Session that individual users can join without adding to their schedule. Our meeting generator then pairs individuals up for short 3-minute meetings, and users can jump from one meeting to the next.
(Heading 2) How do you use 'X'?
In this section, you should give instructions to the end user how they could or should use feature 'X'.
These articles should be comprehensive: though we want to keep these articles concise, we also want to minimise product frustration by providing all the information a user might need:
- When writing participant-oriented articles this means we should assume a basic level of product knowledge and understanding
- When writing organiser-oriented articles this means we should cover all possible fields, parameters and steps
Where possible, keep focused on the feature at hand when writing your articles. If you feel a user may need to have a good understanding of another area of the platform before using the article you are writing, make sure you note this in the introduction rather than the body of the article.
Please refer to the style guide below to make sure you format and style your instructions correctly and effectively. This could mean using numbered lists if there is a clear process to follow when using a feature, or effectively subdividing the article to reflect different areas of a feature.
(Paragraph - Bold) Frequently asked questions
Ideally, we should write the articles in such a way that necessary information is contained within the steps above, or is clearly signposted in the introductory sections. Of course, this isn't always possible, so you may need to include further information within an FAQ section at the bottom of the article.
(Heading 2) Frequently Asked Questions
(Paragraph - Bold) How should I name articles?
When writing article titles, you should use one of the below formats;
- What is 'X' (for catch-all articles that introduce readers more generally to features)
- How to 'X' (for specific issues that don't fit within more introductory issues)
- Or, use exact phrases of the actions they’ll take (such as “Uploading Your First Video,” “Installing Your Plugin,” and so on.)
Part 2 - (Heading 2 - Bold) Style Guide
This part of the guide shows you how to style your articles using Zendesk.
In the body of articles use the 'paragraph' setting. Use bold or italics rather than underlining to highlight key information. If needed, you can link to other articles that users might need to read first (although, bear in mind that users will see other articles from the same section previewed on the left hand side of the screen).
Make sure to use a bullet point list to list out the article's contents. For example, here are the sections that we're going to cover in this article;
- Learning how to format these articles consistently
- Learning how to format 'step-by-step' article templates
(Include a photo of the subject of the article here.)
(Heading 2) Formatting articles correctly
Writing these articles should be very simple once you've read this entire article. Each article will follow a set structure you can adapt for your subject area's needs. You'll notice that the font and some other things are set for the entire article, but there are other things you'll need to watch out for;
- Make sure you use bullet pointed lists, without full-stops at the end
- Include semi-colons before bullet pointed lists (it's the little things that count!)
- Using the correct text formatting options from the list shown below ('Paragraph', 'Heading 1', 'Heading 2' etc.)
- Use gifs rather than annotated images (where possible) to make it clear to users what they should expect to see (and centre-align these images too!)
(Heading 2) How to format 'step-by-step' instructions
N.B. - Before launching into any 'How to' sections of these articles, it's important to introduce exactly what you're about to explain.
In this section, we're going to go through the steps involved in writing a 'step-by-step' how-to, and how you should create and insert gifs into these articles.
(Paragraph - Bold) 1. Create a numbered list
N.B. - Each stage should have a title that allows the user to scan through and identify the different stages that they need help with.
When writing these how-to sections, make sure you use a numbered list to clearly show the order in which steps should be taken.
Do not use the numbered list functionality offered by Zendesk to achieve this, as this restricts important formatting features that we want to use.
Instead, write the number of each step on a new line with a full stop after it at the beginning of each step, as in this article.
Grip Tip - If you have an important tip to give to the user in this type of article, then make sure that you include a Grip Tip on a separate line, with Grip Tip in bold, followed by a '-' in plain text.
2. Write your instructions
Once you've started a numbered list, you then need to start writing clear instructions for the user. For writing-style inspiration, feel free to check out Monzo's style guide!
Grip Tip - Where possible, break paragraphs and numbered lists into smaller chunks to make your article easier to read. Remember, it's a support article, not an essay! (Check out this article about F-Shaped Reading Patterns if you want to find out more about the science behind how readers scan web pages!).
3. Make gifs to bring your article to life
Your written instructions should always be detailed enough on their own to help someone fix an issue or implement a feature. But, not everyone processes information in the same way. You can really increase the quality of your articles by including well created gifs.
You can use tools on websites like https://ezgif.com/maker to convert screen recordings into gifs and drop them easily into the Zendesk article editing tool.
Here are some basic principles and tips for creating gifs (or screenshots when gifs aren't feasible);
- If using your Mac's screen record functionality, ensure you enable 'Show Mouse Clicks' in your video (you can read this article to see how you can do that)
- Keep as much of the screen in view as possible, not just the feature you're focusing on. This gives the reader useful visual context when trying to locate the right part of the page
- Ensure your gifs are no longer than 30 seconds long
- Keep your browser clean (Grip Tip - in Chrome you can now create separate profiles, so you could create a clean profile exclusively for recording processes.)
- Avoid writing instructions directly onto screenshots. Instead, try to combine gifs with written instructions to create clean, yet informative articles
Having followed the above instructions, you should now be able to create clean, clear and concise articles for our new knowledge base.