NOTE: When creating an article that isn't entirely new, please ensure to copy/paste the content into Notepad first, and then into ServiceNow (SN). Notepad is a simple text editor without any formatting capabilities. This helps avoid carrying unnecessary HTML codes into the system. These extra codes can complicate things, such as altering the appearance or functionality of the article in unintended ways.

Short description field

A short description is the title of the article.

• Avoid redundant titles like How to create an article in favor of Create an article.
• Predict how customers will search the topic and incorporate that into titles.
• Make sure they are tuned to be specific without overcomplicating. Examples:
  • Create an article may be too generic.
  • Creating an article using a template in ServiceNow may be too narrow or include information inherent to the task.
  • Create an article in ServiceNow provides some context while staying simple.
• More Tips on writing better Short Descriptions.

Top

Headings

Headings are mostly only used in the Standard template. The remaining templates have their heading automatically structured.

The following heading levels are suggested for use in Standard template articles:

• Heading 2 <h2>.
• Heading 3 <h3>.
• Heading 4 <h4>.

Level 2 headings, <h2> - should be applied to section headings within a feature article. This heading level highlights the importance of the sections over other cordoned elements of the article.
Level 3 headings, <h3> - should be applied to any subsections that fall under a level 2 heading.
Level 4 headings, <h4> - should be applied to third-tier or lower sub-sections within a subsection that falls under a level 2 heading. Writers are not encouraged to include headings below level 4, as the use of such headings could indicate that an article contains an overabundance of content.

Level 1 headings, or Heading 1 <h1>, should NOT be used in an article, as the global style sheet for articles assigns Heading 1 to article titles. To maintain the distinction between a knowledge article title and the sections within the article, writers must avoid using Heading 1 in the body of a knowledge article.
Heading capitalization - Headings should follow the sentence case.  

Top

Bullets and navigation

Utilize ordered or unordered lists rather than manually numbering the steps. Bullets and numbering, in the form of ordered and unordered lists, are crucial elements in an article as they enhance its accessibility. 

NOTE: When you copy and paste documents from an external source into SN, the ul/ol tag includes a specific inline style, <ul style="list-style-position: inside;">, which affects the list formatting. Please remove the part style="list-style-position: inside;" from the string, retaining only <ul> to ensure correct alignment of the list items. You can achieve this by accessing the article's source code using the <> icon in the WYSIWYG Text Editor. 

Ordered lists

Ordered lists should be used to delineate:

• Steps taken to achieve an action (numbered).
• Sub-steps within a series of steps (lettered).

Ordered lists must be created using the <ol> tag. Ordered lists should use Arabic numerals for numbered lists and lowercase English alphabet for lettered lists. Steps within ordered lists must be single spaced. 

Top

Unordered lists

Unordered lists should be used for:

• Table of Content entries.
• Features associated with a system or service.
• Lists of form fields.

The default bullet styles for unordered lists are as follows: 

• Black circular bullets for first order items.
• White circular bullets for second order items.
• Black squares for third order items.

These are set by the global CSS sheet and should not be changed. Unordered lists must be created using the <ul> tag.

Top

Hyperlinks

In general, any hyperlinks should be descriptive so the customer knows where they are going before clicking. It's an accessibility protocol that is also a user experience courtesy. 

Linking to vendor documentation is encouraged over rewriting. It's useful to distinguish where the link is taking customers:

• Review Duo's guide on the Universal Prompt.
• See our article about Zoom Basic Features.

When linking to a PDF, follow this example article:

• To learn how to get started in ELMS-Canvas, read the Getting Started in ELMS PDF or download it from the Attachments section below.

Make sure the hyperlink Target is set to New Window (_blank).

Top

Capturing images from a source

Most of your sources should allow you to download images. In some cases, you may need to screenshot images. There are a few ways to do this, but I find the most simple is to use your operating system screenshot app. Once you have created the file, rename it.

• For MacOS, select Shift + Command + 4 simultaneously. This activates a cursor you can use to choose the area you wish to capture.
• For Windows, select Windows key + Shift + S simultaneously. This opens the Snipping tool, which lets you choose the type of screenshot.
  • After capturing the image, click on the notification in the bottom right corner of the screen to save the image. You can also open the image directly into Paint from this notification.
  • Learn more about other ways to screenshot on Windows.

When capturing, don’t include the border. That will be added in ServiceNow. You may also want to ensure your screen is set to 100% zoom.

Top

Editing images

You may want to emphasize or draw attention to a particular part of an image. For example, the image has a button that the step above tells you to click. In this case, add a red box around the button or object. To create this, you will have to edit the image. Your operating system will already have a basic image editing application.

Note: Do not highlight, circle, or draw an arrow to the object.

Mac OS

Image files will open in Preview by default, a program you can use to edit images.

1. Double-click on the image file.
2. Select the Markup tool to the left of the search icon in the Preview window.
3. Select the Shapes dropdown menu, then click Rectangle.
4. Drag the rectangle over the object you want to emphasize. Drag the blue dots to resize the rectangle.
5. Select the Line color dropdown menu, then click Red.
6. In the top toolbar, select File. Then click Save.

Windows

The simplest way to edit a screenshot or image is to open the file with Paint.

1. Search Paint in the search bar on the Windows toolbar. Click Paint to open it.
2. Select File, then click Open.
3. Select the image you want to edit, then click Open.
4. In the Shapes section on the top toolbar, select Rectangle.
5. In the Colors section, select Red.
6. Drag and drop the red box over the object you want to be emphasized.
7. Select the Save icon.

Adding images

1. Click the Add/Edit Image icon to attach any images to the article as necessary.
2. The Insert/Modify Image window will open. Click on the drop-down menu to the right of the Source field to open your computer's File Explorer (Windows) or Finder window (Mac).
3. Locate the image you wish to upload. Click Open.
   
   • Alternative description for decorative images should be NULL, "".
4. Click the Advanced tab to adjust the Border width and Vertical space.
   
   • Images should be no larger than 650 pixels wide.
   • Standalone images should use a 1-point border width and 10 pt vertical space (Icons, buttons, and other small inline images should NOT use a border or vertical space).
   • Select Solid from the drop-down menu to the right of the Border style field.
   • Images should be positioned under the step of the image references for process documents and processes that are included in feature articles. Place the cursor at the end of the last step and hold shift and press enter (creates <br/> tag inside the <li> element of an unordered list).
5. Click Save.

Top

Reasons to omit screenshots

• Unedited screenshots of an entire window are redundant and they mirror what the user already sees on their active screen.
  
  • These images are unnecessary because the user is already seeing these on their screen.
• The text in the steps is sufficient to explain the action.
  
  • In many cases, it's easier to read a couple of steps or a click path than an image.
• Text is only captured in the image and not in the article body.
  
  • We can't include these images for accessibility requirements. In most cases, these are unedited screenshots of what the user is seeing on their active screen.
• Images are reusing the same menu multiple times.
  
  • Once they see one image of a menu, the text is sufficient to guide user actions.
• If the step needs no further explanation and an image will not offer assistance.
• If the image is not explained in the step.
  
  • Click path images with no steps to accompany them. This is usually confusing to users.
• Images explaining common knowledge like completing a subject and article body field in a standard messaging system.
  
  • Including images for common tasks can quickly bloat an article with images.
• If an image has 4 or more edits it becomes inefficient at highlighting important content and acts in a similar way as an unedited screenshot.
• If an image contains references to steps in the text.
  
  • As the text changes, the image becomes obsolete.
  • There are strict accessibility requirements to publish these images.

Top

Adding PDF attachments

1. Click the Paperclip icon above the article form to open the Attachment window.
   
   • Accessibility standards prohibit you to display them inline.
2. Click Additional Information to open the Additional Information tab. Complete the following fields:
   
   • Display Attachments: Select Display Attachments if you wish for the attached files to be visible to the public.
   • NOTE: Attachments are always visible to DIT Staff who have logged into ServiceNow while viewing the IT Support or IT Internal knowledge bases.
3. Click Save to save your article and return to it later, or click Publish.

NOTE: You can click View next to the attachment. Copy the URL from the browser URL bar. You can use that to hyperlink to a PDF. This prevents having to download a PDF.

Article with instructions on adding images and attachments.

Top

Copy and format the PDF text

1. Highlight and Copy manageable sections of text from the PDF.
2. Paste the selected text without formatting into the body of the article.
   
   • Ctrl + Shift + V on Windows.
   • Cmd + Shift + V on Mac.
3. As you paste, format the text as you work to keep things organized.
   
   • Follow the Service Now Documentation Style Guide to maintain consistency and accessibility.
   • To add a new line without adding a bullet or number, hold Shift and select the enter key.
   • You may have to adjust the text based on how HTML editing and images work in Service Now.
4. Once all the text is copied and formatted, select the Save button.

Top

Tables

Tables can be a critical element to include in knowledge articles, as a strategically placed table can provide an abundance of information in a concise visual format that is easy to navigate. Proper coding of tables is essential to ensure WCAG compliance is maintained. It's mandatory to include a table caption for every table to ensure accessibility. Please follow the instructions provided under the Table Caption section to add a caption to each table you create. Single-cell and multi-cell tables can be created and customized with the Table icon in the Knowledge form WYSIWYG Text Editor. For more information, see Inserting tables in a knowledge article.

Alternatively, tables can be created and customized from the source code of an article using the following basic HTML tags:   

Table caption

Using WYSIWYG editor

1. Select the table to edit. Click on the drop down menu next to the Table icon in the WYSIWYG .
2. Select Table Properties. Table properties window will open. 
3. Under Caption, locate and click on Show caption to select it. Once selected, a checkbox will appear to the left.
4. Click Save.
5. Next, input the caption text at the center-top of the table within the article.

Top

Using Source Code

1. Select a table to edit.
2. Select the Source code (<>) icon from the Text Editor.
3. Insert the <caption> tag immediately after the <table> tag.
   
   • <table> <caption></caption>…</table>
4. Insert the caption text between the caption tags.
   
   • <table> <caption>This is my table caption</caption>…</table>
5. Select Ok.

Top

Sharing articles properly

Share the article using the Copy Permalink link at the bottom of the article. Copying the URL from the browser search bar is not a permanent link and will not work long-term.

Top

Retire an article

After retiring an article, it's important to ensure it's not linked in any other articles. Please perform a search to confirm this.

• Go to Agent View.
• In the filter navigator on the left, type knowledge. Scroll down to Knowledge -> Articles -> Edit to get a list of articles you have access to.
• Click on the Show/hide filter icon at the top left.
• Now set up your search criteria:
  • Choose the Keywords field and input the article number that you have retired. For example: KB0011111.
  • Next, choose the State field and select Published.
• Click the Run button to view any results, if available.
• Eliminate any references to the retired article found in the search results. Also verify that the sentences before and after remain coherent and do not reference the retired article in any way.

Top

Article checklist

The ServiceNow Article Extended Style Guide keeps everything consistent. It's a lot, which is why we have this abbreviated version and the checklist below.

1. Bolding instead of quoting.
2. Images are uploaded properly and aren't broken.
3. Links work and open in new tab.
4. Does it need a table of contents?
5. Are the headers correct (h2,h3,h4).
6. Hyperlinks aren't spelled out urls and are instead phrases that explain destination.
7. Hyperlinks are set to open in a New Window.
8. Use editor to create bullet points or numbered lists.
9. Short description is easily searchable by readers.
10. Short description is specific and concise (avoid phrases such as how to).

Common mistakes

• Unnecessary use of jargon.
• Run on paragraphs.
• Not enough headings to present the information in an organized manner.
• Decorative Images and those that accompany steps that are self-explanatory.
• Displaying PDFs inline.

Top