Table of Contents

Why Help Articles are Important

Internal vs External Help Articles

Best Practices When Writing An Article

Why Help Articles are Important

Back in the summer of 2020 the team sat down and identified a few words we should keep in mind when thinking about the purpose of our help articles. 

Clarify: Display how the platform works, leaving no room for misinterpretation.

Resourceful: Allow customers to search and find answers without requiring a support representative.

Inclusive: Giving any individual with the ability to read the ability to understand the platform. 

Help: Be a positive resource, the first place customers turn to for reliable information. The articles are not cumbersome and leave a user delighted to search for another answer. 

Functionality: Show shortcomings or gaps in the functionality of the platform so customers know to request a new feature or feature change.

Internal vs External Help Articles

Most of the help articles inside our system are designed to help customers interpret the platform, however, we also have internal help articles that should only be accessible to employees. To achieve this we store all internal articles in the category called "Internal Knowledge" and make it private so only employees can see them. 

Best Practices When Writing An Article

Look at examples

If you are new to writing help articles it may be difficult to convey a message. First, take a look at help articles that are already visible to our customers. Read help articles written by major platforms like MailChimp, Hubspot, etc. 

Don't make any assumptions

When writing Help Articles, imagine that the people reading them are complete beginners. Skip the advanced terminologies and jargon, and be wary of mentioning to-dos in passing. It’s safer to assume that customers will need guidance for each step.

Don’t self-sabotage by making assumptions about “simple” instructions. It’s better to over-communicate. More experienced users can simply skim past instructions they don’t need, but beginners will hit hurdles when you leave key details out of our documentation.

Stay consistent in structure from article to article

Every help article should be structured in the same exact way so customers know what to expect and how to navigate. Every article always starts with a table of contents that anchors users to the associated section in the article. Quickly scroll up and down this article and notice that each major section uses H3 and subsections use H4.

Make article content easy to skim

DON'T - Intimidate readers with a wall of text, instead try to break it down into sizeable chunks

DO - Bold, italicize, and capitalize important ideas so users can quickly find the main points.

DO - Use headers, callouts, bullet points, spacing, and visuals to highlight important information and keep the full set of instructions visible at a glance.

DO - Add screenshots and videos of the platform to accompany any written instructions

Use Simple Article Titles

Titles should be kept as straightforward as possible. Restrain your creativity in favor of clarity. When stuck, ask yourself: what might a customer search for?
Remember that people search with basic keywords: “how to create a new event” turns into “create new event.” Create titles that include the operative phrases.
Additionally, rely on action words in the active voice for a majority of your titles:

• “How to (Blank)”
• “Using (Blank)”
• “Setting Up (Blank)”

Or use exact phrases of the actions they’ll take, such as “Creating a New Category” “Uploading a Cover Image” and so on.

Take Advantage of Media

You can write fewer words and make your instructions clearer by including screenshots and/or GIFs showing each step in your interface. Add numbers and arrows to your screenshots that almost make the written explanation pointless. 

Make sure you blur customer and user information from screenshots to ensure we don't get sued. 

Make it easy for users to find

MilkCrate's knowledge base is divided into detailed sections and categories to make it easier for customers and team members to navigate through articles. When writing an article, make sure to categorize your article to a corresponding category (and sub-categories). Add all the tags that make sense, don't hold back.

Review your work & ask for a second opinion

 Always make sure your article makes sense when resting next to other help articles in the same category & subcategory. After you have written a help article make sure you have someone else review your work.