ServiceNow Article Style Guide


Table of contents

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.

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:

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:

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:

The default bullet styles for unordered lists are as follows: 

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:

When linking to a PDF, follow this example article:

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

Top

Fonts

Foreground and background colors play an important role in accessibility. We must ensure they are compliant with ADA standards in all our articles. The default font color set by Cascading Style Sheets (CSS), the standard language for styling web documents, is black, which limits the choice of contrasting background colors. Writers are encouraged to select font colors that meet WCAG AA accessibility standards for both normal and large text. 

To emphasize a statement, use bold text or format it as a note by starting with NOTE: in all capital letters and bold on a new line, followed by the statement itself.

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.

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

Top

PDF attachments

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.

Hyperlink to preview a PDF attachment

  1. Click the attachment paperclip icon.
  2. Click View next to the attachment.
  3. Copy the URL from the browser URL bar.
  4. Use that to hyperlink to a PDF. This prevents having to download a PDF.
    ""

Article with instructions on adding images and attachments.

Linking attached documents to download

These hyperlinks will open the attachment download window without a preview of the attachment.

  1. Highlight the text you would like to link, and Click the Hyperlink icon. 
  2. Click the Link List drop down menu and select the desired document.
  3. Click the Open Link in... drop down menu and select New Window.
  4. Click Save.

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:   

Caption
Tag Description
<table> Defines a table.
<th>

Defines a header cell in a table. Must have a scope attribute that specifies col, colgroup, row or rowgroup. Can not be left empty. 
<tr> Defines a row in a table.
<td> Defines a cell in a table. Can be left empty.
<caption> Defines a table caption or title.
<thead> Groups the header content in a table.
<tbody> Groups the body content in a table.
<tfoot> Groups the footer content in a table (optional).

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.

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

Top