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.