In order for our customers to have a positive experience viewing Knowledge articles, it is important that articles are formatted in a clear and consistent way. When creating Knowledge articles, please follow this guide. This guide shows the correct formatting for articles with text only and articles with text and images.

Guidelines for Knowledge Articles

• Before creating, search the knowledge base to see if there is similar/existing content.
  
  • For Frequently Asked Question (FAQ) articles, if there are more than 10 for a particular service, look to consolidate.

• Reading and Comprehension Considerations

  • Reading and comprehension challenges in written communications are a daily occurrence in all fields, including health care. Below is a short list of conditions and challenges that are very common. Each point is followed by some suggestions about how to design training documents and written communications to help level the playing field for all.
    
    • Simple, plain, and concise language is best for everyone.
    • Avoid the use of medical terms, abbreviations, and jargon when possible. When these terms must be used, spell out abbreviations the first time they appear in a document and define terms as needed.
    • Include plenty of white space on each page. White space is restful to the eye and it promotes one's ability to retain what is learned.
    • Use image editing software to format images to the best possible clarity. Typical features include cropping, sizing, sharpening, contrast and brightness, and the ability to save an image in a usable format so no additional adjustments will need to be made. (Every time an image is re-created into a different format (.pdf, .jpg, .png, etc.) or by successive copy/paste steps, a loss of resolution occurs.)
    • Aim to produce documents with a reading level of around the 9th grade whenever reasonable to do so.
      
      

• Inclusive Language

  • The world is becoming more aware of the common use of language that is unintentionally hurtful and not inclusive to all.
  • The World Wide Web Consortium (W3C) incorporated guidelines on exclusionary language in their W3C Manual of Style.
  • Below is a list of 9 potentially exclusionary words and recommended replacements. Please avoid these terms and review your articles for any other exclusionary language.
    
    

    Exclusionary Word	Recommended Replacement
    master	main
    slave	replica
    whitelist	allowlist
    blacklist	denylist
    grandfather	legacy
    sanity	coherence
    dummy	placeholder
    he/she/him/her	they
    his/hers	theirs

    
    
    

• Grammar Tense

  • Always write in the present tense using the active voice, which is simple, easy to read, and helps to direct users.
    
    • Avoid writing in the future tense or passive voice (was, will, should, should be, etc.).
    • Example: "The Confirm dialog box will appear" should be "The Confirm dialog box appears"
  • Avoid using verbiage containing "you" when possible
    
    • When directing users to do something using step by step instructions, avoid using "you."
    • Using "you" in more detailed paragraphs or scenarios in order to make the concept easier to understand for the end-user is an acceptable practice.
      
      • Not acceptable: You should click the In Basket to open it.
      • Acceptable: Click the In Basket to open it.

Components of a Knowledge Article

• Knowledge Base: Select which knowledge base will contain the article
  • See ServiceNow - Knowledge Bases (KB0016338) for an up-to-date listing of our knowledge bases, including the Content, Viewership, and Contributors for each.
    
    

    Note: As of May 30, 2024, in order to make our naming schema for knowledge bases more consistent and clear, we have made the following name changes to existing knowledge bases: Information Technology will now be Information Technology Public Michigan Medicine Internal will now be Information Technology Protected HITS Internal will now be Information Technology Internal

    
    
  • The knowledge bases most frequently used are:
    • Information Technology Public: Contains customer-facing knowledge that does not require a login to view, supporting our goal of empowering customers to find answers independently 
    • Information Technology Protected: Contains customer-facing knowledge that requires login due to data sensitivity 
    • Information Technology Internal: Contains knowledge accessible only by HITS and TSPs, such as support process maps, networking diagrams, firewall rules, emergency protocols, etc. 
    • MiChart: Contains customer-facing knowledge pertaining to MiChart and supporting services. This content requires login due to the tenets of our contract with Epic. 
• Category: Select an appropriate category for the article
• Ownership Group: Select the ownership groups that will be responsible for approving/maintaining the article throughout its lifecycle
• Valid to: Set to 2 years from creation/revision automatically by the system when a new draft is created. This can be set manually to a specific timeframe, not to exceed 26 months from today's date.
• Short Description: This is the title of the knowledge article. It should include the name of the service followed by a dash and a short description of the intent of the article. (I.e. <Service> - <Short Description of the Article>)
  • Example: Jabber - Multiple Phone Lines

Article Templates

Several standard templates are available for your use.

• Landing Page: To be used as an overview page for an application or service, from which related How To, Knowledge-Centered Service (KCS), and FAQ articles regarding that application or service can be linked. It provides the following sections, but please note that not all sections need to be used. If a section is blank, the section header will not appear in the article.
  
  • Overview: A section to introduce your application/service to the customer, and provide some basic information.
  • Service URL: If the application/service has a URL for access or login, it can be provided here.
  • Related Information: A section for any other information related to the service/application. E.g. How to request access, step-by-step guides, troubleshooting information, etc.
  • Vendor Information: A section to capture information related to the vendor. E.g. Contact name, phone, email, account information, etc. Note: Vendor account information should likely be kept on an internal page vs. public-facing, unless the customer is expected to reach out to the vendor directly.
    
    
    
• How To: To be used to provide step-by-step instructions, information on an established workflow, or additional information about the service.
  
  • Introduction: A section to tell the customer what kind of information they can expect to find within the article.
  • Instructions: A section to provide the content of the article.
• KCS: To be used to provide break/fix instructions or workarounds, or to convey knowledge which is conditional based on the environment.
  
  • Issue: A section to provide details about the issue or degradation with the application/service.
  • Environment: Where is the issue or degradation occurring?
  • Cause: What is the root cause of the issue or degradation?
  • Resolution: What is the workaround/remediation steps for this issue?
• FAQ: To be used when creating an article containing specific customer-asked questions and their accompanying answers.
  
  • Question
  • Answer

Fonts, Styles, and Text Justification

• Font Style and Size
  • Headings: Bold 14pt Arial
  • Body: 12 pt Arial
  • Color: black only
• Text Justification
  • Left-justify all text
• Spacing
  • If information is in paragraph form, insert a blank line between paragraphs.
• Font Styles for Emphasis
  • This section describes template styles defined to make certain words or phrases stand out from the standard paragraph text.
• Call-Out Boxes
  • You can use colored boxes or boxes with a colored border in articles to call-out or highlight important information.
  • Note: If you change the background color of a box, you must also specify the text color. This is important for people using ServiceNow's Dark Theme, as it inverts any colors not specified. E.g. When inverting the Yellow Note Box below, the yellow background would stay yellow, but if you do not specify black text, the text will invert to white. The white text on a pale, yellow background is very difficult to read. A best practice is to preview the knowledge article in both Default and Dark Themes to verify readability for all users.
    
    

    Yellow Note Box Note: In the table properties, the border width is 1, border style is solid, border color is #000000, and the background color is #fafac8.

    
    

    Black Border Box Note: In the table properties, the border width is 3, border style is solid, border color is #000000.

    
    

    Red Border Box Note: In the table properties, the border width is 3, border style is solid, border color is #ff0000.

Steps to Create a Call-Out Box

1. Create a single-cell table by opening the Table drop-down menu, clicking the Table menu item, and selecting a 1x1 grid.
   
   
   
   The result will be a new 1x1 table.
   
   
   
   
2. Select the new 1x1 table, open the Table drop-down menu again, and this time click the Table Properties menu item.
   
   
   
   
3. When the Table Properties dialog box appears, set the Border to 2.
   
   
   
4. Then select the Advanced tab, change the Border Color and Background Color to match the following style, and then click OK.
   
   

   Note Border: #000000 Note Background: #FAFAC8

   
   
   
   Your new callout will then be ready to use.
   
   

Boldface Text

The following describes situations in which you would use boldface.

Italicized Text

The following describes situations in which you would use italicized type.

• Adding emphasis: Use the following guidelines to add emphasis to information in your text.
  
  • If you need to emphasize a word or short phrase within a sentence, use italic font.
  • Example: Independent practices and multi-site users do not have access to the PO Comparisons view.
• Captions for images.

Lists

Bulleted Lists

Use bullets to list items or phrases that do NOT need to be numbered or performed in a sequence.

Parallel Structure for Bulleted Lists

Verify the list is consistently structured with words, phrases, or complete sentences and that the items use parallel construction. Capitalize and use a period only in complete sentences.

Example:

Active accounts may be deactivated for the following reasons:

• You do not use the account for 80 days.
• You violate departmental policies.
• You transfer to a different department.

Numbered Lists

Use numbered lists to list sentences or phrases that DO need to be performed in a specific sequence.

Example:

Use the following procedure to update patient and prescription information.

1. Open the Select Patient/Rx window.
2. Click New Patient.
3. Complete the fields in the Patient Maintenance and Patient Summary windows.
4. Click Save.

Example for bullets and additional information:

1. Click on the Duo Settings tab and then click on U-M Duo Settings.
   
   1. If you have never enrolled before, it will say "Enroll a Device in Duo" and then click Startup to skip to step 5.
   2. If you have enrolled before, click on Manage U-M Duo Account.
2. Click on Add a new device.
3. Select Mobile Phone.

Tables

• All tables should have a set of designated row and/or column headers - this is possible within the ServiceNow editor.
  
  • Example: Highlight the row, click the drop-down arrow next to the table icon in the toolbar, select Row properties, then select Header from the Row Type drop-down.
• This makes this data usable for users of assistive technology
  
  • WebAIM (Web Accessibility in Mind) website

Hyperlinks

Format URLs, email addresses, and references to other guides or guide sections as hyperlinks.

• All active hyperlinks should be blue, underlined text.
• URLs should appear as hyperlinked text (not a site address) for accessibility purposes.
• Use full URLs (including https://).
• All hyperlinks should have Target set to New Window (_blank).
  
  
  
  
• If possible, hyperlinks should be on one line.
• The text of links should be concise, unique, and descriptive. Users of assistive technology rely on this to navigate documents. Read more about how to make good links.
  
• When inserting a hyperlink for self-help articles, be sure to use the permalink (located at the bottom of the article) for articles in ServiceNow.  The link should be formatted as https://michmed.service-now.com/kb?id=kb_article_view&sysparm_article=KBXXXXXXX, where XXXXXXX is the number of the KB article in question.

Images

Use screenshots to display supplemental text. The goal of any image is to clarify text or reduce the need for text. Keep the following in mind when working with graphics:

• All images need to have accompanying Alt Text which should describe the photo or image. See also the below resources:
  
  • What is Alt Text?
  • Writing Good Text Alternatives
  • Writing Great Alt Text for Website Images
• When importing images into a document, be sure to preserve clarity and readability of the graphic.
• Images should be a minimum of 250 pixels wide and a maximum of 750 pixels wide (less if they are indented). Images should be their native resolution and not be skewed or stretched. Smaller images/icons which may be inserted in text may be less than 250 pixels to fit proportionately for viewing.
  

  Note: Always view your article from the Portal to make sure your images and tables are not cut-off.

• Images should not contain any sensitive related information (PHI) and not violate any vendor agreements.

Image Borders

• Images should have a border around the edge of the graphic.
• All borders must be in black or red.
• In Word, you can add a border using the Format Picture command, which is available through a right-click when the image is selected. Use a black line at 1 px width.
• ServiceNow allows you to add the razorline to the images natively.
• Do not add a second border if the image already appears with a solid line border on all sides.

Capturing Images

Only capture what is referred to in the documentation.

• If your text refers to a particular section of a large window, you can capture the smaller section (instead of the entire window) as long as it is obvious to the user where the section is located in the window.
• If you capture multiple windows in the same screenshot, verify that all fields referenced in the documentation are visible.
• Do not use shadow.

Images of Toolbar Buttons

When referring to a toolbar button, consider including an image of the button when appropriate. Smaller images/icons which may be inserted in text may be less than 250 pixels to fit proportionately for viewing.

Example:

Click on the toolbar.

Placing Images

• Images should be left-justified to the text preceding it.
• Add 1 space in between each line of text and the image.
• If the text preceding the image is a bulleted or numbered step, justify the image to the bullet or number.
• Images related to a step (including images with one annotation) should follow the step.
• If an image has multiple annotations, use your best judgment about placing it before or after the steps based on what will be most helpful to the reader.
  
  • Consider using column style formatting if there are multiple steps to follow.
    
    • Example:
      

      Steps	Screenshots
      Step 1: Select the Main Menu option.
      Step 2: Select the Color Control option.
      Step 3: Select the Neutral option. Select Save and Return.
      Note: A notification may appear stating a USB-C Host is detected.
      Step 4: Select Confirm when the notification appears asking to confirm the USB Host Selection.
      Note: The USB-C video and USB devices are automatically detected once these changes have been applied.

Image Callouts and Annotations

A "callout" refers to a combination of a word/phrase and arrow/pointer used to describe a particular field or area on a window or other image.

• Callouts can be styled for use on-image or off-image.
• Use black text only.
• Use red for border and or arrow/pointer.

Off-Image Callouts

Example: Below is an example of callouts placed outside the image.

• You may choose to place callouts above, below, or to the side of the image, depending on what you are calling out in the image.
• Not every callout requires a box around the item you're pointing to.
  
  
  
  
• The off-image callout text is styled as follows:
  
  • Font: Calibri
  • Font size: 9 pt.
  • RGB Color: F0283C
  • Text is justified left.
• The off-image boxes and arrows are:
  
  • Width: 1 px
  • RGB Color: R240, G40, B60

On-Image Callouts

There are times when it makes more sense to place callout text within an image instead of outside the image.

• Place your callout text over the unused part of the window instead of outside the window. This saves space on the page and enables you to use larger windows if you don't have to reserve room for callouts to the left or right of the window.
  Example:
  
  
  

Alternate Callout Colors

If the windows in your document have so much red text on them that red callouts will not stand out enough, consider using a different color for your callouts. However, when changing the callout color scheme, be consistent throughout the entire document.

Writing Step-by-Step Instructions

• Do not repeat text from written steps on annotations in a screen capture. Use numbering in the annotation to reference brief steps beneath the image. If steps are written in, be sure they repeat the same information.
• Typically, a step contains a single action. Steps that contain multiple actions should be broken out into separate steps.
• Combining actions into one step is appropriate when it's used in simple data-entry scenarios.
• Use brief steps that begin with a verb, such as:  "Click OK in the Sample window" rather than "In the Sample window, click the OK button."
  Example:
  
  1. On the Login window, type your user name and password.
  2. Select a server.
  3. Click Save.
• Restart numbering when you add a new heading, procedure, or exercise.

Order of Content - How To and KCS Articles

Every article should follow the same order of content sections. Some of these sections are optional and should be used if applicable.

1. Short description
   
   1. Each article should contain a short description that lets the user know what function the article will teach the user. It should only be a few sentences.
2. Before Beginning (optional): 
   
   1. If the instructions require the user to complete an action or requires specific hardware/applications then a section labeled Before Beginning: should be used. Use a bulleted list for required hardware/applications. If there are existing articles that are relevant to this section, please hyperlink them. When inserting a hyperlink, be sure to use the permalink (located at the bottom of the article) for articles in ServiceNow or the share link (share icon on the top right) for articles in the Knowledgebase.
3. Step by step:
   
   1. The main section of the article should describe in a step-by-step process how to complete the task. The process can be shown to the viewer using only text,  a combination of text and images or by using video.
      
      • If the process you want to describe is more intuitive using images or you want to call out specific items, then use images in this section of the article.
      • If using a narrated video seems like the best way to demonstrate the process, then submit a general request with the Customer Experience team (Service Catalog) about creating one.

Further Resources or Troubleshooting

If the process you are describing in the article has common issues or problems, it is recommended to split these out into individual articles. It also allows topics which may have a lot of resources/troubleshooting (E.g. Outlook) to stay concise. ServiceNow has the ability to link articles, so that they will appear in the sidebar of ServiceNow.

Video

Some detailed knowledge articles benefit from instructional videos so a customer can easily watch the process for setting something up, completing several steps, or getting the right access. Knowledge videos rely on subtitles and screen capture (not music or narration) so they are accessible and viewable without the need for audio. If your article uses video, you will still need a short description in text format and any applicable prerequisites or further resources. 

Videos are produced in 1920x1080 resolution and should be put in a 700 px wide frame in the article.

To request a video, submit a ServiceNow ticket to Customer Experience. Please include detailed directions in your ticket so the desired actions are re-created when HITS Customer Experience produces it.

Additional Resources for Creating Videos

Live Captioning

Video Accessibility Checklist

Adding Flowcharts to a Knowledge Article

Lucidchart

1. Login to Lucidchart.
2. Click on the + New button in the left sidebar.
   
   
   
   
3. Create your flowsheet.
4. Click on File > Embed to save the embed code you will need to add to your article.
   
   
   
   
   
5. The Share window will open. In the Size field, select Custom. Set the Width to 700 and the Height to 525.
   
   
   
   
6. Highlight the provided HTML and press CTRL-C to copy the code to your clipboard. Click Done to close the window.
   
   
   
   
7. In your knowledge article, place your cursor where you would like the LucidChart to display, then click the Source Code button (<>) from the toolbar.
   
   
   
   
8. Click CTRL-V to paste the code to the cursor location in the document, then click Ok.
   
   
   
   
9. The LucidChart will now be embedded within the article. Zoom tools at the bottom of the window will allow viewing of details within the chart.
   
   

Visio on the Web

Note: Michigan Medicine M365 documents have enhanced security, preventing the ability to open a document to the public internet.  When a user who is not already authenticated to M365 tries to view an embedded Visio document in the Michigan Medicine Help Center, the document will not render.  For that reason, the Knowledge Managers do not recommend using embedded Visio files.  The files can either be imported to LucidChart or can be converted to a PDF or image file and added to the article.

Adding Sections of Code to a Knowledge Article

To add a block of code to a knowledge article:

1. Within the knowledge article form, click the Source Code button on the toolbar.
   
   
   
   
2. An HTML source code window will pop up on the screen. Enter <pre><code>, then the code, and close the tags with </code></pre>.
   
   
3. When the article is published, the code will appear in a shaded grey box.