Support Portal Articles – Best Practices

Template

See: Support Portal Knowledge Base Articles – Creation Template

Guidelines

Before making a new article, perform a through search of Public, Level 2, and Internal articles to determine if an article already exists covering the desired topic. Use different search terms, including with and without hyphens, where applicable. A recent review found several examples of duplicate content.

Can an existing article be updated rather than making a new article? While keeping the lengthiness of articles in mind is wise, also consider that more articles make keeping them updated more difficult.
Does the new article you wish to write provide value? If it only adds a tiny bit of new information, it may be better to update an existing article rather than creating an entirely new article, and/or linking to an existing article.

Do not create an article that simply links to another article, with no new information, as seen in this example:
If you need to link to another article from the one you are writing, can you link to a search result for related terms rather than creating a hard link to an article?

Hard linking to a specific article could create a broken link in the future. This does not mean you cannot create a hard link, but it is a consideration to make.
When creating links, enable the “Open in new tab” toggle. This will cause links to open in another browser tab so users do not lose the article they linked from.
When possible, do not hard link to external blogs and articles. Again, this could create broken links in the future.

One such example found linked to an external product that was no longer a valid URL. Some others linked to Microsoft KBs that no longer existed. Instead, it is preferable to write the content into our own article, rewording carefully to avoid plagiarism or simplify the explanation. Users can still perform search engine queries outside the portal if they need more detail than we provide about a technical aspect of protocols or operating systems.

Also be sure to avoid linking directly to competitor content, such as an Axis whitepaper or a Hanwha user manual.
Do not use unlicensed images from other sites to explain technical concepts. If you cannot create an image/diagram on your own, you may be able to find assistance from others within Support or from JCI resources.
Try to create clear and legible screen captures. Avoid using a phone’s camera to capture a screen shot as this can appear unprofessional. If help is needed, inquire with other Support team members for help or for tools that can assist with this.

Greenshot is a recommended free tool for help in creating still image screen captures.
Set Client to Light Mode, which is the default client appearance, when making Client screen shots and captures.
Check the size of the images or screenshots as they appear in the published article on the portal. Are they too small or blurry to read?
Do not include full article titles as Tags. This defeats the purpose of tags. Tags should be considered like keywords, usually just one or two words in length. A bad use of this can be seen below:

In the article above, the entire title is listed as a Tag. A better option might be separate Tags for ‘license’, ‘licensing’, ‘how to’.
Do not include a period at the end of an article title.
Do not set Headings to ‘Bold’. As headings, they are already preformatted.
Do not repeat the same instructions under different headings. As an example, one article found listed the exact same text as both the Issue and as the Solution.
Try not to overuse Headings. Article Headings create entries in the Content fields, which can be useful in navigating lengthy articles. But are they necessary to navigate, particularly in very short articles?
When listing the “Steps” involved in reproducing an issue or the solution… use an Ordered List. Simply change the block from the bullet point list (un-ordered) and select the icon with numbers for an ordered list. This is more logical when steps in a specific order are involved.
Include version information of the affected Exacq software or camera firmware! Without version information there is no indication as to when a specific bug or issue affects the reader. Additionally, they would not know when a bug fix or enhancement resolved an issue or changed the configuration setup.
Provide some kind of details on the issue. In the below example, there is nothing about versions of software, firmware, or the specific models and/or generation of cameras. This could imply to a customer that JCI’s own camera brand is a bad product. We want to avoid that where possible. Instead, indicate the specific models or generation this applies to, as well any exacqVision versions affected.
When including information/steps regarding different versions of software or operating system in the same article, list these top-down from newest to oldest. This makes finding the latest version information on the top of the article the easiest to find. This is also an appropriate use of Headings so that readers may use the Contents section to quickly be taken to the steps for their version.
Where necessary add tags that include alternate English spellings. i.e. – Color / Colour
Do not add plugin tags or log level tags to standard articles as this will add them to the Log Reference. Log Reference posts require specific formatting.

Special Tags

In addition to standard tagging the following specific tags control the exposure level of the post to various user groups on the support portal.

Guest = Anyone who visits the support portal can view
Level 2 = support techs, Internal and Admins
Internal = L3 and Admins

Standardized Spellings for Articles

exacqVision Web Service or Web Service – when referring to the product
web service – lowercase, when referring to the generic concept
exacqVision Desktop Client, exacqVision Client, or Client when referring to the product
client – lowercase, when referring a generic concept
Panelless – this always throws a spelling error, but Kantech materials are using two l’s
KT-1 – use dash in product name to match
exacqVision Mobile – new mobile app that replaced previous versions and uses direct server communication
Exacq Mobile 3 – old mobile app, requires web service
Exacq XXXX – use single word with capital E for hardware products
exacqVision XXXX – used when referring to software products