Ubiquiti Help Center Guidelines

Overview


This article defines the Help Center's guidelines to be followed when creating, requesting or updating an article. For questions or comments, please send us an email at helpcenter_feedback@ubnt.com.

Table of Contents


 

 

 

 


Processes to Follow 


Back to Top

There are several people involved in the creating and publishing of an article: the article requester, the article author, and the article publisher (Help Center team). The requester will submit a request for a new article, and if it is an internal request, then they must provide an author. The author will create the content and follow some very basic structural and formatting guidelines (explained below) and pass on the content to the article publisher. This will be the person that will actually create the article in the Zendesk Help Center and format it following the guidelines described in this article.  

Requesting an Article

Back to Top

To request an article, fill out this form. You will have to supply an author for the Help Center team to get in contact with, as well as the article title, a short overview and why the article request is being made (e.g. new release, repeated question in forum). 

Creating and Submitting an Article

Back to Top

Article drafts are to be created in Google Docs, by filling out the article templates provided. There must be minimal formatting, since it will not be carried over to the Help Center. These are the guidelines to follow when creating an article:

  • There should only be two font sizes: one for the body of the article and a larger one for the titles and subtitles. 
  • Text will all be in the same color.
  • Notes should be in Italics.
  • Bold should only be used to emphasize an important word or words, but not for a full sentence (e.g. a title, subtitle or step).
  • Terminal Commands must be differentiated by highlighting in yellow. Nothing else in the article should be highlighted. If there is an instruction in between Commands (e.g. press enter), then that needs to be un-highlighted. 
  • Steps and sub-steps must be numbered. Zendesk's numbering allows only whole numbers, so avoid using decimals or letters for sub-steps since these will have to be changed. Numbered Steps will look like this:
  1. Step one
    1. Sub-step 1 of Step 1
  2. Step 2
    1. Sub-step 1 of Step 2
    2. Sub-step 2 of Step 2
      1. Sub-step 1 of Sub-step 2 of Step 2
  • Dot Bulletins may be used for lists.
  • There shouldn't be any other punctuation marks used as bulletins, instead of step numbers, or to denote commands. 

These are the sections that must be included in the article drafts. Click on the links below to find a description of each within this article.

Before writing an article make sure to take a look at these other sections as well:

Follow these steps to submit an article draft:

  1. Access the corresponding article template by clicking on the following links: Work Instruction/Descriptive Article or Question & Answer Article.
  2. Copy and paste the template into a new doc and fill it out.
  3. Name the new doc with the following naming convention: Draft Product Line - Title (e.g. Draft UniFi - How to Set Up an AP)
  4. Send an email with the article draft link to helpcenter_feedback@ubnt.com. The email subject should be the article title.

Updating an Article

Back to Top

To update an article, access the Google Doc draft of the corresponding article. Links to the drafts can be found in the Knowledge Base Article Inventory. Request for access by sending an email to helpcenter_feedback@ubnt.com. Highlight in red anything that must be deleted. Highlight in green all new content to be added.

Note: if content to be removed or added is a Command, and hence is highlighted in yellow, make the font red for content to be removed, and green for content to be added instead.  

Using the Correct Software


Back to Top

In order to keep a unified look and feel to the Help Center articles, the following software will be used exclusively:

  1. Jing: for screenshots and annotations. Download here. Note: it is free software, but you will have to create an account.
  2. Google Docs: to create the article draft and share it with Help Center team.
  3. Zendesk Help Center: to be used to format the article for its final version. 
  4. Gliffy: to create flowcharts. Download here.

Format


Back to Top

Unity in format is vital in keeping with the integrity of the Ubiquiti brand as well as its Help Center's graphic identity. The most important elements to consider are: color scheme, font, standardized images and annotations.   

Color Scheme

Back to Top

Colors used for annotations and any other mark up to highlight or draw attention to a certain area of an image must be:

Over dark background
  • Light Blue HEX#00A0DF (RGB 0, 160, 224)

    Sample Text
  • Light Gray  HEX#E0E0E0 (RGB 224, 224, 224)

    Sample Text
  • Off white HEX#FAFAFA (RGB 250, 250, 250)

    Sample Text
Over light background
  • Dark Blue HEX#025D8A (RGB 2, 93, 138)

    Sample Text
  • Mid Gray HEX#CCCCCC (RGB 204, 204, 204)

    Sample Text
  • Dark Gray HEX#1A2B33 (RGB 26, 43, 51)

    Sample Text

 Learn how to select the correct HEX color code in Jing here.

Epic CSS and RGB conversions courtesy of Matt B ;-)

Font

Back to Top

When formatting articles on Zendesk's Help Center, font guidelines are the following: 

  • The font used will be the standard one (do not change in the HTML tab).
  • All font will be in same color (Zendesk HC standard), except links which will be the standard blue, following the Zendesk HC theme.
  • Font size
    • Main text: size Normal
    • Titles and Subtitles: size Large
    • Unobtrusive elements, such as "Back to Top" links or messages of less importance: size Small
  • Notes will be in size Normal and in Italics. 
  • Bold may be used to highlight important words. Avoid using it for main text.
  • Terminal commands will be differentiated by using the <pre> tag in the HTML code. 
  • Titles for sections will be followed by a horizontal line, by using the <hr> tag in the HTML code.

Images

Back to Top

The width of the articles in the Help Center is set to 920 pixels when screen is at 100% zoom. Therefore, when using images and screenshots in articles, the maximum width is 920 pixels. Make sure any relevant text is legible when image is at its Actual Size.

Another important consideration when taking screenshots, is to have the menu and desktop language in English. The only exception to this is if the image will be used exclusively for an article in another language. For example, a screenshot of a menu in Spanish can be used exclusively in an article in Spanish. However, when creating article translations, it is not necessary to take new screenshots in the different languages. It is understood that the official language for the Ubiquiti Help Center is English. 

Setting Pre-determined Templates


Back to Top

Templates will usually make life easier. Read below how you can set the Ubiquiti Help Center color palette in Jing so the colors are always at hand. 

Screenshots with Jing

Back to Top

To create a pre-determined color palette in Jing follow these steps:

    1. Next time you use Jing to take a screen shot, click on the color box in the left-hand-side menu and select Other. 
    2. A color dialogue box will appear. Select Color Sliders and make sure the drop down menu is set to RGB Sliders. 
    3. Copy and paste the HEX code provided in the Color Scheme section of this article in the Hex Color space. Make sure you are pasting only numbers and not the number sign (#). When you click enter, the desired color will appear in the color box at the bottom left-hand corner.
    4. To save this in the blank palette, just click and drag the new color into the small gray squares at the bottom of the dialogue box. The color will now appear in one of the small squares. Repeat this with as many colors as you want (up to twenty colors). You can overwrite the pre-determined palette by dropping a new color on top of the one you want to replace.
        

Article Structure 


Back to Top

There will be different kinds of articles in the Help Center, each one with its different structure, but there will be some structural elements all articles must include:

Title

The title must begin with the product line name followed by a dash and a short but descriptive title for the article. It is important to remember that the search results focus first on article titles. So make it a good one. 

For example: UniFi - How to Configure Multiple Sites

This title accomplishes three things: it narrows down search results to the specific product line, it lets the user know it is a work instruction, also aptly named "How-to's", and finally, it communicates the article's objective at a glance. 

Table of Contents

The table of contents' formatting will be explained in more detail in the following section. Authors should just make sure to include in their draft the list of sections and subsections that will be found in the article. It is helpful to create the table of contents before starting to write the article, and use it as an outline to follow.

Remember that the section names must be descriptive enough so readers can know what to expect at a glance. When creating Work Instruction articles, each step will be a section, and each sub-step a sub-section. Step titles and sub-titles should begin with an action verb (e.g. Configure, Add, Delete, Click, etc). 

Sections

In the body of the article, each section will be in Large font, as mentioned previously in the Font section and will be followed by a horizontal line, which can be created in the HTML tab with the tag <hr>. Subsections will similarly have the same sized font but will not have the horizontal line. All sections and subsections will have an anchor that will lead readers Back to Top in Small font.

Overview

The first section, that will come before the table of contents in the article, will be the Overview. This section should describe in a condensed fashion what the article will accomplish. If applicable, it will also state what problem it is going to solve, in what environment it will happen, and what the solution will be. 

Table of Contents

Back to Top

The table of contents will be linked to the different sections within the article, to help the reader navigate it easily and efficiently. Ideally, the table of contents will be visible in its entirety without scrolling down when the screen is 100% zoom.

Two-Column Table of Contents

Back to Top

With longer tables of contents it might be necessary to have it split in two columns, to ensure its visibility in one screen. Organize text in two columns and begin numbering the second column at the number of choice, by changing the <ol start="#"> as seen in the example below:

<div style="float: left; width: 50%;">
<ol>
<li>First Section</li>
<li>Second Section</li>
<li>Third Section</li>
</ol>
</div>
<div style="float: right; width: 50%;">
<ol start="4">
<li>Fourth Section</li>
<li>Fifth Section</li>
<li>Sixth Section</li>
</ol>
</div>


The result would be the following two columns. Notice the second column begins numbering at four, as specified in the html code above. 

  1. First Section
  2. Second Section
  3. Third Section
  1. Fourth Section
  2. Fifth Section
  3. Sixth Section


To insert subsections, the rich text toolbar can be used. Simply select the section you wish to indent, click on the icon for Align/Indent  and select the option of indent right. 

 

Anchor Links

Back to Top

Anchor links help readers navigate around a webpage by taking them to specific sections of the page with a click of a link. There are two elements necessary: the anchor itself (the section the user wants to reach), and the link pointing to that anchor (the clickable name of the section in the table of contents). 

To create the anchor you must name it and insert the html code below in front of the title of the section. For example, in order to make the title of this subsection "Anchor Links" an anchor, the following code is inserted before it. 

<a name="anchor links"></a>

While in editing mode, an icon of an anchor will appear where the anchor was inserted.

In the actual html code, to also include the font size which is larger for a title, it would all look like this:

 <a name="anchor links"><a/><span class="wysiwyg-font-size-large">Anchor Links</span> 

To add the link to this anchor there are two options. In the Zendesk HC editor you will be able to select the anchor link using the rich text tool bar. Follow these steps to do so:

1. Highlight the word you will link and click on the Insert/edit link icon on the toolbar.

 

 

2. Select the anchor name from the drop down menu in the dialogue box and click OK. Your selected words will now appear in blue and underlined (indicating they contain a link). 

  

 

The second way to do this is inserting the anchor link in the HTML tab by using the code below:

<a href="#anchor links">Anchor Links</a>

 

Work Instruction Article (How-To's)

Back to Top

A Work Instruction article will guide the reader step by step to accomplish an objective. This objective might be anything from initial set up and configuration, to solving a problem, to updating firmware. It might have many steps and sub-steps or it might be a very simple action that needs only two or three steps. In either case, it should be treated as a How-To article and each step should be numbered and separated accordingly. 

Work Instructions should not be wordy. Use the least information possible to have the reader perform an action, instead of burying each action inside a mountain of text. Images are helpful when further explanation is needed.

Work Instruction Articles must include the following:

  • Title
  • Overview
  • Table of Contents
  • Steps
  • Sub-steps (if necessary)

For further information on what the Overview and Table of Contents should contain return to the Article Structure description.

The title of Work Instruction Articles must state the action that the reader will be performing, and it must begin (after the requisite product line name) with the words "How to". For example, if the problem is incorrect configuration of an AP, the title of the article should be something like: "UniFi - How to Configure an AP".

Additionally, each step title must begin with a verb: the action the reader needs to perform. The step and sub-step titles must be short and concise. If further explanation is needed, it can be added below the title, in the body of the article.

Each step must appear in the Table of Contents. It is not necessary, however, to include sub-steps in the Table of Contents if they do not represent a complete action. For example, if a sub-step is "Log in", it is not necessary to have it appear in the table of contents because that step alone won't really help a user: it is part of a bigger action. If in doubt, go ahead and include sub-steps in the table of contents.

Question and Answer Article

Back to Top

The Q&A Article is the simplest one in structure. These articles will only have two elements: the title, which should be the question (it still must begin with the product line name); and the answer, which will be the entirety of the body of the article. 

These articles have the characteristic of being short and answering one question only. If a longer explanation is needed or a step-by-step instructional, then the article becomes either a Work Instruction Article or a Descriptive Article and must follow the corresponding structure. 

Descriptive Article

Back to Top

A descriptive article does just that: it describes something to the reader. It could be describing a new feature, or describing the difference between two product models. What it should not do, is describe a process or how to accomplish something. If you find yourself doing that, then take a step back and consider writing a Work Instruction Article instead. 

The Descriptive Articles must include the following:

  • Title
  • Overview
  • Table of Contents
  • Article Body (with separate sections, if applicable)


For further information on what the Overview and Table of Contents should contain return to the Article Structure description. 

The title in the Descriptive Articles should begin with the product line name, followed by a title that at a glance will let the reader know what they're getting out of the article.

Important Considerations


Back to Top

To finish off, take a look at a few other things you should keep in mind when writing an article. 

Links

Back to Top

When formatting the article in Zendesk, make sure that all links (except anchor links) will open in a new tab and not take your reader away from the Help Center.

To set this, select "New Window" as Target when inserting a link.

 

Verb tense and narrator

Back to Top

It is important to use simple present tense and never to write in the first person. Instead of saying: "I clicked on the link to access the controller", you can either say "Click on the link to access the controller" for a Work Instruction, or "The controller can be accessed by clicking on the link" for a Descriptive Article. 

Acronyms, IT Specific Terms and Jargon

Back to Top

When writing an article start with the assumption that the reader has no knowledge on the subject. When using acronyms, always write the words out fully and use the acronym in parenthesis when it is first mentioned. You may continue using just the acronym for the rest of the article.

As for IT specific terms and jargon, you can either define them the first time they are used, or link them to their definition in the Help Center Glossary (Coming Soon...).  

Related Articles

Back to Top

Always add at least three related articles at the end of your piece with the corresponding links. It will help the user navigate through the Help Center. 

Basic Articles (Coming Soon...)

Back to Top

Since you must write assuming that the reader has no knowledge on the subject, this sometimes means that there are basic actions you might need to explain very often in the different articles. To avoid this, you can add a link to one of the existing Basic Articles that explains that specific activity. If a Basic Article for that activity doesn't exist yet, go ahead and write it and send it to the Help Center team along with your main article.  

A reader of any level should be able to understand the Help Center articles with the assistance of the Basic Articles.

Labels

Back to Top

The labels in an article assist the search engine in finding the correct article. Since titles must be short and concise, add labels that you believe might be words users will use to search for the topic you are writing about. This is an exercise of putting yourself in your reader's shoes. 

All articles must come with at least three labels (different from the article title). When creating the article in the Zendesk Help Center, add labels by using the right-hand menu. Type the word or words and click on "Add new label". It will appear in the blank space. If the label has already been created by someone else, it will appear when you start typing. Select it by simply clicking on it.  

Powered by Zendesk