You are going to write a Knowledge Base article (KB article) in ServiceNow. This article will help you understand best practices to successfully write a useful KB article.
Table of Contents
1. Knowledge Base Article Lifecycle
KB articles have a lifecycle and it is important we understand that lifecycle. The KB article flows through different stages of the lifecycle. These stages are called Workflow States. The workflow states appear across the top of the ServiceNow Knowledge Base edit screen.
The current Workflow is the section underlined in blue and is not greyed out.
The Workflow States:
Draft: The creation phase.
Review: Waiting for review.
Published: Once published the article is available to users of ServiceNow in searches.
Flagged/Expiring: Article has been flagged to expire. Stays in this until an editor either edits and publishes the article or confirms the article can be retired.
Retired: Article is marked as retired and is at the end of its lifecycle.
2. Write Content
Search Knowledge Base before creating a new article
Before writing a KB article it is important to search the Knowledge Base for any existing articles which might cover the topic you are considering writing an article about. If an article exists that covers the topic it is best to not duplicate the knowledge. If you find the existing article is lacking relevant data, edit the article rather than creating a new article. Creating additional articles for the same topic will cause confusion. It is best to edit the existing article and bring it up to the needed standards.
Find existing resources
Before creating an article, do a search for existing resources. Many times these existing resources can fill the need. If you find a resource that has the needed step by step instructions or videos, you can link to these instructions in the KB article. If the instructions are generally correct but need just a few changes to meet the needs of the University, you can still link to the instructions, but also include the necessary information to adapt the instructions.
Curate the content in a KB article
If you have found resources that will serve the purpose of a KB article, create a KB article that describes the links to the resource.
- Create a KB Article following approved standards.
- Provide context for the resource link in the body of the article. Also include any adaptions to the instructions if needed.
- Link to the resource. It is better to link to the resource than to copy the information.
Write simply
The audience at the University varies greatly. The understanding of the English language can be significantly different depending on the readers' experiences. As a general rule you should write at a 6th grade level. Here are a few other items to pay attention to when writing:
- Use Plain English: Avoid big words. Use terms young kids would understand. Use less syllables for a higher impact.
- Define Acronyms: People do not understand acronyms. The first time you use an acronym in an article, spell it out and follow it with the acronym in parentheses. Example: Virtual Private Network (VPN). The next time you use it in the article just use the acronym.
- Avoid Jargon: Not everyone understands the jargon we use in our circles. Many times jargon used is acronyms, in this case define the acronym.
- Use Active Verbs: In your sentences use the active voice not passive.
- Example:
- passive: The files will be deleted by clicking on Delete.
- active: Click Delete to delete files.
- Example:
Construct article for easy scanning
People are impatient. Especially, when looking for information. They want it to be easy to find. Once found, they want it to be clear, easy to follow and to the point.
When users do a search for an article they will scan titles. If the title sounds like something they want they will click on it. This does not mean they will read the article. They scan the headings and any introductory sentences. If these peak their interest they will finally read the article. As creators of KB articles we need to make the articles easy to scan.
- Titles should be descriptive and meaningful
- Articles "Overview" should be brief
- Text should be chunked into topics and subtopics using headings
- List items should be bulleted
- Instructions should be numbered step-by-step
We want to be short and to the point. People don't have time to waste reading your fluff (like this sentence).
- Use familiar words
- Keep sentences concise
- Paragraphs should be short
Writing article titles (Short description)
Article titles are the first thing the knowledge base will look at when a search is performed. This means a well written title can greatly increase the chances of an article being found in a search.
Follow these guidelines when creating article titles:
- Start with the software or platform name
- Example: Canvas: Add a Course
- Note: avoid having the verb in the 'ing' form. Use 'Add' rather than 'Adding', 'Create' not 'Creating' etc.
- Be brief. Brevity is key. Title should be concise. Ideally less than 10 words and should summarize the content.
- Use words users will most likely search.
- Use the active voice, e.g., create, assign, secure
- Do not lead with commonly used words such as "How to."
Note: ServiceNow automatically generates the title of an article based on the title field. It serves as the summary heading for the article and is automatically formatted as a Heading 1 (H1). For accessibility, a web page should only have one H1. Do not repeat the title in the ServiceNow text field.
Summarize the article
The first paragraph of every article should be a brief description of what the article covers. This can be a single sentence. You should write to address the audience directly telling them why they might want to read and apply what is in the article.
Example
Before: This article has instructions on how to install Microsoft Office 365 from outlook.usu.edu
After: You can have Microsoft Office 365 on your PC, but first you need to install it. The following instructions are for installing it using outlook.usu.edu
You should not put a heading for the articles description. The title of the article will serve as the heading.
Organize content
If your article is long or has many different steps or items, it is best to break the content into topics, users find long lists or many paragraphs difficult to scan and follow. (Remember: People have short attention spans.)
Headings
Use headings to identify topics and subtopics. Headings help:
- Provide a quick overview
- Divide up the content
- Helps users quickly decide if they need to read the content or not
- Helps you the writer organize the content
Headings should describe the process. You should not use "How to" in topic or subtopic headings.
Using Bulleted and Numbered Lists
Bulleted lists are used when the order of the list does not matter. If you have two or more items in a row and order does not matter, this is the list to use.
Numbered lists are used when the order matters. If you have more than one item in the step-by-step instructions, this is the list to use.
Using lists will help the user easily read and process the information. Lists generally should not exceed nine items. If you need to exceed this try to break down the steps into sub topics.
Table of Contents
If your article has two or more headings, unless it is short, you need to include a Table of Contents. The Table of Contents should be linked to the heading in the article. Learn to create a Table of Contents.
Uploading Images
Images need to be uploaded to ServiceNow. Simply dragging and dropping the image into a KB article will display for the author but will not display for users on and off-campus.
IMPORTANT:
- Each image in a KB article must be UPLOADED.
- Images must have a unique file name. If the file name already exists in the image library the image will fail to upload. If this occurs, change the file name and try uploading the image again.
- Images may be re-sized once uploaded into a KB article.
- Images may be re-used in other KB articles by using the steps below. To re-use an image click the Image Library and search for the image.
Upload an image:
- Click the insert / edit image icon on the tool bar.
- Click Browse for an Image.
- Once the image has been uploaded the image may be re-sized and re-used in other KB articles.
Using Images
Images should be clear and easy to see. To make this possible. especially when using screen shots or the snipping tool to create images, you will need to make sure to resize what you are going to screenshot to a smaller Window size so it can be clearly seen without being extremely large. Meaning if you have a larger monitor reduce the size of the window before doing a screen shot. This will help keep the image clear without being too large for the document.
Bad Example: Image on 27" monitor using full screen then resized for this article.
Example: Good Image taken on a smaller Window and also resized when putting in document.
Doing the above makes the images easier to read. Not always perfect, but easier to read.
Using Images in a List
When using images as part of a list, you will find it makes the image part of the list. For example:
- This is an example list
- The image became Number 2. in the list. To solve this problem, after putting in the image, hit SHIFT-Enter until the cursor is past the image. Then just hit enter and your list will continue.
- Example of number 3.
- 4 Is how it should look.
Using links
Using links in an article can help the user find the information they need. However, if the links are improperly used it will complicate the process for the user. Links should:
- Provide information when read
- Provide the title of the target page or explain what the link is offering to the user
- Be at the end of a sentence or as close to the end as possible
- Links should not be the hyperlink itself unless it is not possible to provide a link associated with descriptive text
When creating links avoid using phrases like "For more information see here". For example: Request and Email alias
All external links should be set to open in a new window (Target: New Window).
If a link will download a file, make sure it is included in the link information so the user is not surprised. For Example: Download Cobbler Recipe
For further assistance, please contact your Department IT Support or the IT Service Desk