Tips for writing and publishing KB articles

Brief Description

This document is intended to provide recommended formatting for writing and publishing KB articles. We begin with a brief description of what the article is about.

Who is your audience?

We write knowledge base articles to provide information and self-help to the intended audience. It is important we ensure our knowledge base articles are clear and concise, and speak in understandable terms.

• Acronyms should be spelled out with their first use and if an explanation or reference is necessary please provide one.
• Instructional steps should provide appropriate detail to assist the reader in completing the task.
• Using screenshot images and other examples are helpful.
• Be intentionally descriptive.

Formatting the Article Body

Table of Contents

Using the Table of Contents feature will give the reader a quick view of the KB article and quick links to each section.

The TOC is built from the various headings, each nesting the TOC bullets from "Heading2-6". This KB is an example of using Header2-4 and the construction of the TOC.

The TOC should also be placed at the very beginning of the KB article, before your content.

Whenever you modify the section headings you can update the TOC using the "Update" button.

Section Headings

Useful for breaking out details of the article.

Please use Heading2 when creating primary section headers and heading 3-6 for subheadings within those sections. Heading1 does not render as well on the IT website.

Imbedding Links in the Article Body 

Often external links can run into problems if opened within Service Now KB articles. It is best to use the "New Window" feature to open the link in a new window.

Create the text for the link.

Example: Please see the SLAC IT home page for details.

• Select the text you would like to imbed the link, in this example "SLAC IT home page".
• Click on the Insert/edit link button in the tool bar.

• Paste or type the URL into the popup window and select "New Window" in the target drop down.
• Click "OK"

Restricting Access

The kb_view UI page is public - Users are not required to log in to view knowledge articles, unless one of the following is done: 1. roles allowed to view the article are selected; 2. the knowledge article is restricted by using the Can Read field; 3. the knowledge base in which the article resides is restricted by using the Can Read user criteria.

The IT website is now public, we must keep that in mind.

• KBs created in the IT Knowledge Base are public
• Approved published KBs are pulled into the website through an overnight process 

Setting permissions

Setting “Can Read” and “Cannot Read”

• “Public” (by default)
• “Loggedin Users”
• Specific group (ex: “Service Desk”)

Related Articles

A related "Related Articles" section is a good way to provide other helpful information for their reference in a list.

• Imbed the link in descriptive text (see notes on "Imbedding Links in the Article Body")
• When linking other KB articles, use the IT website URL for the corresponding KB article
  
  • This only applies to publicly available KB articles. 
  • You may link to non-public articles by copying the KB article permalink. 

Related Articles (example section)

Get IT Support

Tips on Writing IT KB Articles

IT Marketplace Pricing Information

Search for duplicates

Use the "Search for duplicates" function in the KB article creation form to look for articles that may closely match the content of your draft. You may find that your content is already available, or could be added to an existing article. Prior to creating your KB article you can also search the knowledge base using a key term to find like articles.

Use Meta Tags!

Meta tags are very important in helping people find the information they need by creating appropriate search terms.

They can be simple one word tags or multiple words in quotes. 

Other Notes

Images

You may use images and screenshots to support the text. Please follow these simple guidelines.

• JPEG format
• Size them around 640x480
• Create space around the image within the text

Alt text

Images that support the content require a text description (also called "alt text") that communicates the purpose and/or content of the image. This information is presented to the individual using assistive technologies allowing them to hear the description of the image.

When writing alt text: 

• Be descriptive: Summarize the image’s content accurately.
• Keep it concise: Aim for around 125 characters or less.
• Focus on relevance: Describe the most important aspects of the image.
• Use keywords: Include relevant keywords for SEO and accessibility.
• Avoid redundancy: Don’t repeat information already in the surrounding text.
• Consider context: Think about how the image contributes to the overall content.
• Prioritize clarity: Ensure anyone can understand the image without seeing it.

To add alt text, select Insert/edit image from the edit options menu. In the "Insert/Edit image" popup, fill out the "Alternative Description" field. 

Tables

This in an example of a simple table.