Knowledge Base Style Guide

We've compiled a guide of best practices to help you write content for your Help Center. 

Using the Active Voice

Create content in which your user is the subject of the sentence performing the action. Using the active voice is more direct and concise.
For example:
Incorrect: Clicking on the image will enlarge it.
Correct: Click the image to enlarge it.
Incorrect: Many new features are included in the Enterprise package.
Correct: The Enterprise package includes many new features.  

Using the Present Tense

Write in the present tense to make it easier for your users to read. Avoid using the words “will” and “shall.”
For example:
Incorrect: The following error message will be displayed: Please fill in a valid URL. 
Correct: The following error message is displayed: Please fill in a valid URL. 
Incorrect: Clicking New will create a new article. 
Correct: Click New to create a new article. 
Tip:
Using the future tense is acceptable when writing feature requests.

Writing in Second Person

Talk directly to your user to provide clear and direct instructions. 
For example:
Incorrect: The advanced settings can be accessed from My Account.
Correct: Access the advanced settings from My Account.

Working With Lists

Use numbered lists for steps that need to be completed in a sequential order. 
Use bullets for single-step procedures and to list items that do not require a particular order. 

Using Gender Neutral Language

Keep your content gender neutral.
For example:
Incorrect: The user can change his template settings.
Correct: Users can change their template settings. 

Avoiding Slang and Jargon

Slang and jargon are context and cultural sensitive. Using such terminology can confuse users and complicate localizing efforts. Try to limit the use of slang and jargon, while staying true to the company’s tone and voice.    

Using Abbreviations and Acronyms

Spell out acronyms the first time you include them in an article. 
Write the full term, followed by the acronym in parentheses. 
For example:
A mail exchanger record (MX record) is used to map a domain name to a list of message transfer agents for that domain. 
You do not need to spell out: 
  • Acronyms in a title. 
  • Common industry-standard acronyms, such as URL, IP address, ID, HTML. 

Working With Titles

Capitalizing titles:
Capitalize the first letter of each word in a title.
Do not capitalize articles (e.g. the, a, an), coordinating conjunctions (e.g. for, and, nor, but, or, yet, so) or prepositions (e.g. in, on, by, at, from), except when they are the first or last word of the title.  
Writing procedural titles:
Use the gerund form (…ing ending) for procedural titles.
 
For example:
Adding Lists to an Article
Writing Known Issue titles:
Use the following format for Known Issue titles: Day (number), month (text), year (number), hyphen (‐) followed by the title content.

For example:
16 April, 2020 - Unable to Edit a Text Box in the Editor
Writing error message titles:
Use the following format for error message titles: Error Message: <error message content>.

For example:
Error Message: Your Account is not Valid
Writing Feature Request titles:
Use the following format for Feature Request titles: Request: <title content>.

For example: 
Request: Creating Product Name Variables 

Documenting User Interface Elements

Bolding user interface elements:
Bold the names of User Interface (UI) elements (e.g. menus, tabs, buttons, fields, checkboxes, lists, windows, icons) when writing procedures. 

For example: 
  1. Click the Pages Menu from the top bar of the Editor. 
  2. Click the relevant page. 
  3. Click the Show More icon. 
  4. Click Page SEO

Do not use bold on non-procedural content. 
For example: 
You can exclude a specific page from search engine results, by hiding it in the Page SEO section. 
Capitalizing user interface elements:

Capitalize elements as they appear in the UI. 
For example: 
Open the Media Manager. 

Capitalize the names of UI elements that do not have labels. 
For example: 
Click the Settings icon.  

Using Notes and Tips

Add informative notes to draw your customers' attention to important and useful information.
Tips: Give customers best practices and use cases.
Tip:
Use notes and tips sparingly. 
Notes: Highlight important information. 
Note:
You can easily change the type of informative content block you use.  
Important Notes: Highlight information which is crucial to the completion of a task. 
Important:
Save or publish your changes before you exit the Content Editor.
Warnings: Highlight information that is of critical nature. 
Warning:
Deleting a content block will permanently delete the content. 

Using References

Title names that appear as links should be capitalized as they appear in the title.
For example:
Links that are part of the sentence should not be capitalized.
For example:
Tip:
Do not bold references. 

Writing Numbers in Your Content

Spell out numbers when they appear at the beginning of a sentence. Otherwise, use numerals rather than words. One exception is if you are mixing the use of numbers, for example "Enter two 3s."

Incorrect: Over one hundred million users have created at least one stunning website with Wix.
Correct: Over 100 million users have created at least 1 stunning website with Wix.

Related Articles

Getting Started With Your Knowledge Base Articles

Get started creating the articles you can use in your Help Center, Widgets, and Ticketing System. After researching the questions your customers ask, you'll need to categorize the information. Then you'll have a structure in place to begin creating helpful articles. As your products and services grow you'll need to stay on top of updating your articles regularly. Tip:Remember, creating supportive content takes time, so approach it one step at a time and stay organized. Step 1 | Research and Outline Your ArticlesTo better understand the articles you’ll need, find out the questions your customers are asking. This will help you identify common threads and provide a basis for your category list. Where to look: Community forums: See what questions customers are asking each other, and in which areas they are experiencing the most difficulty. Social media channels: Customers often go to social media to look for help or express frustrations. Support tickets: Identify your customer’s main pain points by analyzing support tickets, chats, and calls.Support agents: Make a list of popular issues and themes your support agents have come across.Step 2 | Create Categories for Your ContentThink about the information you need to include and divide it into main categories that your customers can easily choose. Here are 5 main categories you can begin with: Getting StartedSetting UpManaging Your AccountAccount SettingsBilling and PricingYou can organize your content into categories and subcategories. Learn MoreStep 3 | Create Your ArticlesThink about your target audience — are they beginners, experts, or intermediate? Try to keep your language eye-level, so everyone can easily understand. Also consider both visual and verbal learning styles. You can include screen captures, videos, html code, links to related content, and more. You can create three different types of articles:Informative ArticleThis is the basic article type that is great for product overviews, step-by-step tutorials, and more. Unlike Feature Request and Known Issue articles, this article type does not need status updates. Learn more about creating an Informative article. Overviews: An overview provides a general summary of a service or product. Use it to summarize and provide CTAs (call to actions) for your customers to do next. Add images or videos to help get your message across and create a clearer picture. Tutorials: A tutorial or 'how-to' article breaks down step-by-step how something works. This is great for anything that takes more than 2 steps to complete. You can also choose to go into more or less detail, depending on what you’re breaking down. Tutorials are also great as videos. Feature RequestA Feature Request article allows you to inform and update customers about features you don't yet offer. They can help you determine which products or services your customers want most, so you know what to develop next. Feature Requests display statuses like &quot;Working on it&quot; so customers know what to expect. Learn more about Feature Request articles.Known IssueA Known Issue article lets you notify users and collect complaints on bugs that you're aware of. They can also help reduce the number of support tickets by telling users that you're working on solving the issue. Known Issues display statuses like &quot;Working on it&quot; so customers know you're fixing the problem. Learn more about Known Issue articles. Step 4 | Update Your Content RegularlyA help center is ongoing - just like your business. When you’re up and running, read the information below to understand how to maintain the best help center you can as your company grows. Update your content on an ongoing basis, based on:New features: Create articles for new features and update feature requests to reflect relevant releases.Changes to existing features: Always update your articles to reflect changes to your products and services.Known issues and bugs: Make sure to update the life cycle status of Known Issue articles as the issues are handled and addressed.New tickets (customer feedback): Keep tabs on what your customers are asking about to update existing content or generate new content as needed.  Analytics: Use Wix Answers Insights to examine how your customers are engaging with your content. If you see that a large number of tickets were opened from a particular article, it could indicate that you need to update the article. Also, check which of your articles are receiving the most unhelpful ratings and make updates accordingly. Learn MoreWhen updating your content, make sure you update:Article content: Update and improve existing text, make sure to edit screen captures and videos when your user interface changes. Related content: Update the list of related articles to improve existing content and to include new content. Check out the Wix Content blog for tips on building a professional knowledge base.

4 min read

Creating an Article

Articles are the core of your Help Center. You can create 3 different types of articles for different needs. The following is intended to walk you through the process of creating an Informative article. You can also create:Feature Request articlesKnown Issue articlesInformative articles are likely the most common type of content you'll create for your Help Center. Create Informative articles to introduce features, provide step-by-step instructions, answer FAQs and more. To create an Informative article:Click the Knowledge Base icon in the side panel.Click + New Article at the top right.Leave the Informative Article type selected. (Optional) Select a category for your article from the Category drop-down. Note: An article must be in a category before you can publish it. You can move it to a category later.  Click Create Article.Enter the title of the article in the Title field. Tip:Save your work early and often by clicking Save at the top right. Click the Write something field and enter content for the article. Hover over the left side of the content block and click the Add a block icon . Choose a type of content block to add to your article:TextClick the Text icon and select a text type:Text: Add a standard block of text. Learn how to format your text.  Bulleted: Add a bulleted list. Use bulleted lists for single-step procedures or to list items that don't require a particular order. Numbered: Add a numbered list. Use numbered lists for multiple-step procedures that require a particular order. Learn more about adding text to your articles. SubtitleClick the Subtitle icon and select an option:Subtitle: Select a heading size to add a subtitle. Anchor: Add an anchored subtitle in the H3 heading size. Tip: Once you add a subtitle, you can hover over it to change the size or to add or remove an anchor.Informative NotesClick the Informative icon .Select a color: Green, Teal, Red, or Yellow.Enter the note title in the Title goes here field.Enter the note text in the Write something field.Tip: Hover over an informative note to hide its title or change its color. Learn more about adding informative notes. LinesClick the Lines icon.Select Dashed or Solid. Tip: Once you add a line, hover over it and click the Edit icon to change the line type.Image Click the Image icon . Click Upload. Select a file from your computer and click Open. (Optional) Add image alt text: Hover over the image and click Add Image Alt Text. Enter the image's alt text and click Save. Note: Uploaded images display at a maximum width of 628 px. When clicked, they expand in your browser window. Learn about other ways to add images to your article. VideoClick the Video icon .Paste the URL of the video.Click Get Video.Note: Currently, it is only possible to add URLs for videos uploaded to YouTube or Vimeo. Learn about other ways to add a video to your article.TableClick MORE and select Table.Enter the number of columns and rows that you need.Note: The header is automatically added on top of the table, so there's no need to add an extra row for it. Click Add Table.Learn how to add, delete, or edit your table. CollapsibleClick MORE and select Collapsible.Enter the title in the Title goes here field.Enter the text in the Write something field.Learn more about collapsible blocks. Code SnippetClick MORE and select Code Snippet.Select the type of code snippet you'd like to add. Tip: Hover over a code snippet and click the Edit icon to change the snippet type.IFrameClick MORE and select IFrame.(Optional) Edit the iFrame height.Enter the URL you'd like to embed in the iFrame URL field.(Optional) Click Disable scrolling to prevent scrolling within the iFrame. Click Add iFrame.Note: By default, a horizontal scroll bar appears when the width of the iFrame is more than 700px. Click Disable scrolling if you want to remove the scroll bar.HTMLClick MORE and select HTML.Double-click HTML Code and remove the existing code.Enter your HTML code.MarkdownClick MORE and select Markdown.Enter text using Markdown syntax. Click outside the Markdown block to preview the formatting you've written. Learn more about adding Markdown text.10.  Click Save at the top right.11.  When you're ready, click the Save drop-down and select Publish. 12.  (Optional) Select publishing options (Notify followers or Update URL). Show me more Notify followers: Send an automatic notification to followers of the article. Learn More Update URL: Update the live article's URL (if you've changed the title of the article). Note: The old article URL will redirect to the new URL.13.  Click Publish Article. Tip:View the live article once you've published by clicking View Live next to Save. 

4 min read

Getting Customers to Utilize Your Help Center Content

So you've created your awesome Help Center, with tons of great articles. But how do you get your customers to utilize it? We have compiled a list of suggestions, based on our experience, to help drive traffic to your Help Center. Your Site's Header and FooterMake it easy for customers to find your Help Center by adding a link to BOTH your site’s header and footer. Adding a link in your footer menu is important, but to get maximum exposure, we suggest adding the link to your site's header as well. When a user is looking for assistance, they usually want an immediate solution. Add an easy-to-locate accessible link in your header, so customers click it instead of actively needing to scroll to your footer to find it.As your site's 'real estate' is expensive in headers and footers, we suggest using one of the following terms to link customers to your Help Center:SupportHelpA simple icon such as '?'Campaigns, Emails, and Customer SupportTake advantage of all lines of communication with your customers to steer them to your Help Center:Campaigns: Marketing campaigns are a great opportunity to get customers to engage with your knowledge base content. When announcing new features, include links to relevant articles to help customers get started and preempt any questions or concerns they may have. Emails: Include a standard link to your Help Center at the end of your emails. It can be part of a closing sentence: Or part of the email footer:Customer Support: Make sure to link customers to the relevant Help Center articles when providing support.  Embed Widgets in Your ProductUse widgets to easily provide context sensitive help, right inside your product!Create a help widget that opens within your product that customers can use to search for relevant content, without ever leaving the page. Wix Answers allows you to set up help links embedded within your product that open widgets displaying specific articles. To get started with widgets: Create a new widget.Define which knowledge base content to include in the widget.Embed the widget within your product or site.Share Your Help Center on Social MediaPromote your Help Center on your social media channels by including links to relevant articles.Get Found by Search EnginesMany factors affect your search engine ranking and Wix Answers is built with SEO in mind. You can control many aspects of your Help Center SEO. We have compiled the following list to help you optimize your content:Generate unique contentGenerate a lot of relevant contentInclude relevant keywords within your title and contentGenerate traffic to your Help Center (see the sections above)Use the Related Articles feature and add links to other articles within your Help CenterUpdate your sitemap to include your Help CenterTips:Click here to learn how to optimize your Help Center articles for search results. Click here to learn how to edit your Help Center's SEO settings.

3 min read