Overview

The Division of Information Technology (DIT) Knowledge Management (KM) style guide sets forth the formatting and stylistic guidelines writers should follow when creating articles for a DIT knowledge base.

How to use this guide

Follow the guidelines in the KM style guide. Where the KM style does not provide answers, refer to the DIT Editorial Guidelines. Where the DIT Editorial Guidelines do not provide answers, refer to the Associated Press (AP) Stylebook.

For spelling and grammar guidance, refer to the Merriam-Webster dictionary.

Top

Knowledge Management mission statement

Collecting and sharing the knowledge that demystifies technology and empowers our customers

The Knowledge Management group is devoted to accumulating and sharing knowledge on information technology with the students, faculty, staff and affiliates of the University of Maryland that will help to build a community of informed and capable technology users.

In pursuit of that mission, the Knowledge Management group pursues the following course of action:

• We collaborate with the minds that build, support and use technology on and off campus to construct, collect and house knowledge on the information technology resources available to the University of Maryland.
• We examine the knowledge we acquire and develop to ensure its accuracy and clarity.
• We maintain an evolving library of information that is accurate and accessible.
• We deliver accurate, vetted knowledge and information in a timely and expedient manner.
• We adapt our delivery of information to the needs and expectations of our audiences.
• We promote new knowledge acquisitions, technology and services using a diverse set of delivery methods to reach as many users, customers and consumers of knowledge as possible.
• We seek new pathways through which we can better accumulate, build, maintain and share knowledge with our collaborators, on and off campus.

Through this course of action, we aim to empower technology users within and beyond the campus community by building an accessible, accurate and diverse repository of knowledge that can evolve in response to the rapid growth and expansion of new technologies as well as the ever-changing needs of the campus.

↑ top

General considerations when creating knowledge articles

The IT Library houses knowledge articles that provide visitors to the IT Service Center with information about systems, services and resources offered and supported by the DIT. As a contributor to the IT Library, your goal is to compose a knowledge article that clearly and concisely presents information on these systems, services and resources. The clarity and concision of your article contributes to the visitor's ability to comprehend and retain the information presented in the article.

To that end, knowledge articles should demonstrate the following qualities:

• Clarity.
• Concision.
• Cohesion.
• Polish.
• Formality.

Clarity

Knowledge articles should aim to present information clearly. Information presented in Knowledge articles should be presented in Plain Language. Language in knowledge articles should be designed to appeal to a lay audience that may have minimal interaction with technology and technical processes.

Simplicity is key to clarity. Use active voice, common words, "you" and other pronouns, and short sentences and paragraphs.

Concision

Knowledge articles often detail complex processes. However, the structure and language of these articles should be designed to provide complex information in a simple and restrained manner. Readers need information quickly and wordy, long-winded articles can prevent their ability to grasp and comprehend information swiftly.

Concision should not come at the expense of detail and description. Writers should seek to compose articles that prioritize information that is critical to reader comprehension but does not sacrifice detail.

Cohesion

Knowledge articles should focus on one topic or process per article. In some cases, articles may address related topics or processes within one article space, but these sections must all relate to the core topic or process that has been designated as the focus of the article.

Cohesion is an essential component of an article with strong flow. Articles that flow well are easier for our readers to read and learn from. Cohesive articles employ a narrow focus that gives reader the information they have sought without distraction or digression.

Pursuing cohesion does not preclude referencing or linking to articles on related topics. Such connections can expand the scope and depth of an article, and these connections can improve readers understanding of relationships between DIT services and systems. However, outside of navigation pages, referencing or linking to related topics should be managed judiciously and these references/links should not be prioritized over the designated focus of the article.

Polished

The IT Library is a public-facing resource that should always aim to meet our readers' expectations of professionalism. Knowledge articles should be presented without grammar or spelling errors. A careful review of an article before publishing can help to prevent unpolished error-laden writing from being published.

Tone

The tone should be conversational. Use the second person ("you") to refer to customers and users as long as it does not cause confusion.

Follow Plain Language guidelines.

Jargon and slang

Slang is defined by Merriam-Webster as "language peculiar to a particular group" and "an informal nonstandard vocabulary composed typically of coinages, arbitrarily change words, and extravagant, forced, or facetious figures of speech". Slang should be avoided altogether.

Jargon is defined by Merriam-Webster as "the technical terminology or characteristic idiom of a special activity or group". Jargon should be avoided where possible. If it is impossible to avoid jargon, it must be defined for the reader.

Top

Types of knowledge articles

Knowledge articles may be composed in various formats, depending on purpose and target audience. Most articles follow standard style guidelines. There is one type of article that may not, which is generated through a process called knowledge-centered support (KCS).

KCS articles

This type of article is created from an Incident in a process called knowledge-centered support (KCS). This article is made up of the following sections (in order):

• Description of issue.
• Environment.
• Underlying cause.
• Solution.

The description of the issue should use the customer's own words with first person pronouns. For example, "I get an error when I log into to TERPmail."

The environment refers to the product or service in question (there may be more than one). It may also include: the operating system, the browser (including version), use of virtual private networking and more.

Top

Formatting and style standards

The following section of the KM Style Guide details formatting standards for process documents and feature articles.

Formatting standards are applied to both article types using the What You See Is What You Get (WYSIWYG) text editor in the Text field in the ServiceNow Article form.

To learn how to access the article form and create a new knowledge article, read Create a Knowledge Base Article in ServiceNow.

Font and font size

Font

Source Sans Pro

Font Size

14 px

Source Sans Pro 14px is the default font and font size set by the ServiceNow Cascading Style Sheet. DO NOT select an alternative font or font size when entering text into the Article Form Text field. If text is pasted into the text field, it must match the default font and font style.

You are encouraged to Paste and Match Style or Paste text without formatting to ensure that default font and font size are maintained in final published document. Alternatively, you may copy and paste text into the Text field and remove any font-specific <span> tags in the article's source code to make sure the default font and font size are applied.

The default font color, as defined by the Cascading Style Sheets for all articles, is black. This limits the background colors available for use against contrasting backgrounds. Writers are encouraged to choose font colors that pass the WCAG AA accessibility standards for both normal and large text.

The following colors have been verified for use as contrasting background colors according to WCAG AA accessibility standards:

• #FFF6F9 (light red).
• #EEF8FF (light blue).
• #F0FFE9 (light green).
• #FFF6E1 (light orange).
• #FFF7D6 (light yellow).
• #FCF6FE (light purple).
• #F7F7F7 (light grey).

Example code:

<tbody>
   <tr>
      <td>Individual students, faculty and staff may purchase personal Multi-factor authentication (MFA) hardware tokens from the Terrapin Technology Store located on the ground floor of the Edward St. John Learning and Teaching Center (ESJ)for $20 USD plus tax. To purchase a hardware token, you should bring your&payment;and a;University ID card. After you purchase the hardware token, you will need to&amp<a title="register" href="https://itsupport.umd.edu/itsupport?id=kb_article_view&sysparm_article=KB0010934" target="_blank" rel="nofollow">register</a>&ampit to your account.&ampContact the&amp<a title="" href="https://it.umd.edu/terrapin-tech" target="_blank" rel="nofollow">Terrapin Technology Store</a>&ampfor more details on purchasing a hardware token.&amp
      </td>
   </tr>
</tbody>
</table>

Bold text

Feature articles and process documents must include bold text to designate the following types of terms:

• Buttons to click on a web page or web form.
• Fields to complete on a web page or web web form.
• Radio buttons or checkboxes to be selected on a web page or web form.

Bold can be applied using the Bold icon (B) on the WYSIWYG Text Editor in the ServiceNow Knowledge Form or by applying the <strong> html tag around the selected text using the Source Code window, which can be accessed via the <> icon in the WYSIWYG Text Editor.

An example of bold text in a knowledge article can be seen in this example: Click Enter a Passcode at the MFA authentication prompt.

Headings

Headings are a required component of feature articles and are good practice for other article types. 

The following heading levels are suggested for use in feature 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. In This Article should use this heading.

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 sentence case.  

Bullets and navigation

Bullets and numbering, in the form of ordered and unordered lists, should be used to delineate a variety of content within knowledge articles.

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. 

Unordered lists

Unordered lists should be used for:

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

Unordered lists should use the following, default bullet types: 

• 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.

Tables of contents

Articles with more than three headings should include a table of contents. 

Tables of contents follow the "In this article" heading and should use the unordered (bulleted) list tag <ul>. It is acceptable to have a sub-list one order deep, but no further. Table of contents should be hyperlinked to the referenced section and should be included whenever an article has 3 or more headings.

For example:

In this article

• List item 1
• List item 2
  
  • Sub-list one order deep
• List item 3
  
  • Sub-list one order deep
    
    • Sub-list two orders deep (not acceptable)

"In this article" should not be followed by a colon.

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. However, tables must be coded correctly to make sure they do not compromise WCAG compliance. 

Because single cell tables Single cell tables may NOT be most used for providing the following information:

• Notes.
• Disclaimers.

Notes are short statements, no more than one to three sentences, that contain additional information about a process, system or service.

Similar to notes, disclaimers are short statements that provide a warning or caveat about the content that is presented before or after the disclaimer. Disclaimers should not exceed three sentences in length. 

View an example of how to incorporate notes and disclaimers into a knowledge article at the following link: https://itsupport.umd.edu/itsupport?id=kb_article_view&sysparm_article=KB0013356

Multi-cell tables may be useful in providing the following information:

• Lists of features associated with a service or system.
• Comparisons of features between multiple services or systems.
• Comparisons of features between current and past versions of systems or services.
• Staff listings that contain contact information.
• Staff directories.
• Service directories.

Multi-cell tables can include an accessible color in the heading and where else appropriate. The selected color must contrast the font used in the cell so as to ensure the text is accessible to screen reader software. 

Single-cell and multi-cell tables can be created and customized with the Table icon in the Knowledge form WYSIWYG Text Editor. Alternatively, tables can be created and customized from the source code of an article using the following basic HTML tags:  

List of tags a table must include.

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.
<colgroup>	Specifies a group of one or more columns in a table for formatting (optional).
<col>	Specifies column properties for each column within a <colgroup> element (optional).
<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).

 

To learn more about creating and customizing tables using HTML tags, visit W3 Schools HTML Tables page.

Example code:

<table style="background-color: #eef8ff;" border="1">
   <caption>  This is a caption </caption>
   <thead>
      <tr>
         <th scope="col">    This is a header   </th>
      </tr>
   </thead>
   <tbody>
      <tr>
         <td>    This is a data cell in the body   </td>
      </tr>
   </tbody>
   <tfoot>
      <tr>
         <td>    This is in the footer   </td>
      </tr>
   </tfoot>
</table>

Checkmarks

When including a checkmark in a table or article text, the checkmark should be an image with the alt text modified to "checked". In a table, a blank <td> element is acceptable but all <th> elements must be filled in. A blank box can be used as a placeholder.

The image for this can be found, when editing a KB article, by going to the Additional Information tab and selecting to lookup images for the Image option. The image for checkmarks will show under the name "images/check32.gif". The blank box for empty table cells will show under the name "images/16square.gif". These images can then be copied once selected. However, remember to delete that changed Image value under Additional Information afterwards by pressing the lookup images button and selecting "clear image value" on the selector.

Links

Links are important not only for navigation, but also because they suggest relationships between web pages. The right link in the right place can enhance reader's comprehension of the documented process.

Links should not simply indicate where to point a browser, but should also include two other attributes: Target and title. The target attribute tells a browser how to load the new document, while the title attribute provides additional information about the link to browsers and other programs (such as accessibility readers). If the link is also an image, it must use the alt attribute.

It's always preferable to link keywords or the title text of a webpage, rather than typing out the URL. Links leading to a different page should open in a new window (target=_blank).

When linking to an article in the Knowledge Base (whether in an anchor tag or a regular link), you should use the article's permanent link (permalink). Use the following format for an article permalink, where KB#### is the article number: https://itsupport.umd.edu/itsupport?id=kb_article&article=KB######. Example: https://itsupport.umd.edu/itsupport?id=kb_article_view&sysparm_article=KB0012345. 

Anchor links

Anchor tags are required for articles with a table of contents. Each heading following the table of contents must include a link to the top of the page.

For instructions on creating an anchor tag, refer to W3docs How to Create an Anchor Link to Jump to a Specific Part of a Page.

Use only keywords. For example, when linking to a section titled "Uploading an image to the library," the anchor tag should read: uploading-image-library.

Separate keywords by a hyphen. For example: umd-faq. Do NOT use a space or underscore.

Anchor tag links MUST use the _self target attribute. For example: target=_self.

Top of page links

Links to the top of the page should be used in articles where there are 3 or more headings. Top of page links should be used at the end of each section and should not include any direction arrow. Top should be capitalized. Remember to include target=_self for the top of page link.

Click paths

When describing a series of links to navigate through to reach a desired webpage, list in bold text the links, buttons, fields, etc. to click in order, with each phrase separated by an image of the greater than sign, which should have alt text "and then" as well as a height and width of 12.

Example: Home Directory IT Support File a ticket

The image for this can be found, when editing a KB article, by going to the Additional Information tab and selecting to lookup images for the Image option. The image will show under the name "images/modified_list.gif" and can then be copied once selected. However, remember to delete that changed Image value under Additional Information afterwards by pressing the lookup images button and selecting "clear image value" on the selector.

Top

Attaching files and PDFs

Do NOT display a PDF in-line. This option displays the attached PDF in a frame inside the knowledge article portal view. It is not recommended for reasons of accessibility and mobility.

Instead, PDFs should be attached to the KB for viewing and download by the reader. The content of a knowledge article does not need to duplicate an attached PDF (and in some cases, duplication should be avoided, such as for reasons of proper attribution). Rather, write a paragraph introducing or explaining the PDF and then link to the attachment. Use this same method for linking externally.

Content owners and contributors will sometimes want to attach forms to a knowledge article as a PDF. Forms should NOT be attached to a knowledge article. If an article or an attachment is better suited for a form or request format, direct the content owner to the ServiceNow administrators at sn-admin@umd.edu. ServiceNow administrators can create forms and requests in ServiceNow.

Top

Horizontal rule

Use of horizontal rule or <hr/> to distinguish sections should be avoided. Instead, use an appropriate heading level code.

Top

Code blocks

Any instance of code in an article must be placed inside of <code></code> tags that are then surrounded by <pre></pre> tags. The <code> tag indicates the given text is code and the <pre> tag means pre-formatted text, which preserves any spacing and line breaks as well as keeping the font at a fixed width.

Top

Linking outside the knowledge base

Linking outside the knowledge base is acceptable when giving attribution, direction customers to documentation and other circumstances. If Knowledge Management does not have the rights to duplicate content (with or without attribution) and good documentation exists elsewhere, you should link to it.

When linking outside the knowledge base to documentation, write a paragraph introducing or explaining the documentation and link to it. This is a similar process for attaching files and PDFs.

Top 

Valid to 

Valid to date field should be updated manually every time the article is updated. The recommended date is one year from the edit date.

Top

Writing guidelines

Title standards

Titles for articles should be entered into the Short Description field of the ServiceNow Knowledge Form and should adhere to the following formula:

Action + Service or System

This formula is designed to emphasize the action being explained and system/service being used to perform the action in process documents.

A sample process document title may be displayed as:

Log into a UMD Box Account

This formula can be adjusted for feature articles that do not cover a single process. Titles for feature articles must include the name of the system/service that is the subject of the and the scope of the feature.

A sample feature article title may be displayed as:

Overview of Google Drive File Stream

Title capitalization

Titles should be capitalized according to the Headline Capitalization style suggested by the AP StyleBook.

Run your title through the Capitalize My Title tool with AP Style selected to verify that your heading is capitalized properly.

Review How to Correctly Use APA Style Title Case for more information on heading capitalization.

Top

No Oxford comma

The Oxford comma, also known as the serial comma, should not be used before "and" or "or" when listing items unless necessary for clarity. In general, follow this rule:

• Correct: apples, oranges and plums.
• Incorrect: apples, orange, and plums.

Top 

Latin terms and abbreviations

Latin terms and abbreviations (such as, i.e., etc., et al., e.g., ibid. and so on) should be avoided where possible. Instead, these terms and abbreviations should be written in plain English for clarity to the reader. Use the Word Usage and Consistency List to find common Latin terms and abbreviations and their recommended plain English translation.

Latin terms and abbreviations may not be avoided in some circumstances, such as policy or legal documentation. In these cases, err on the side of caution and do not alter the language.

Top 

Acronyms

Use of acronyms should adhere to the conventions set forth in the DIT Editorial Guidelines. The central tenet of these guidelines is that the full proper name or title of a system, service, organization, etc. must be presented before an acronym is used in its place.

Before using an acronym to refer to a system, service or organization, writers should present the full proper name of the subject in an introductory paragraph or sentence. The full name of the subject should be followed by a parenthetical statement that contains the acronym to be used in subsequent references.

The following examples provide some basic guidance on introducing acronyms.

• University of Maryland (UMD)
• Enterprise Learning Management System (ELMS)
• Division of Information Technology (DIT)
• Multi-factor authentication (MFA)

Optional Plurals

Always avoid using optional plurals. Use the plural form of the noun instead. For instance, instead of writing "Content Owner(s)", you should write "Content Owners".

Top

First person plural

Do not use first person plural (that is, "we"). Instead, define who is doing the action.

Examples:

Incorrect: We are reaching out to all department managers about this issue.
Correct: DIT-HR is reaching out to all...

Incorrect: We did this in order to improve security.
Correct: DIT Security made these changes to improve security.

Images

Add or renew an image

Images are an important part of knowledge articles. However, they should be used only when necessary to demonstrate an important or potentially confusing feature. Images also pose a number of accessibility concerns that you MUST be aware of and how to mitigate any accessibility issues. Images should be positioned under the step the image references for process documents and processes that are included in feature articles. This can be done using the <br/> tag inside the <li> element of an unordered list.

To add or renew an image, follow the steps below.

1. The recommended way to get an image into your article is to insert the image or attach it before embedding it in.
2. Check out a new version of the article if the article already exists.
3. Click the Insert/Edit image icon on the tool bar.
4. Select Attachment for the Type field.
5. In Image, click on the drop-down list. Navigate to the desired image and select the image.
6. Click Open to upload the image.
7. Refer to Inserting Images: Methods and Tip for details.
   
   • Set Border Thickness to 1 and Vertical to 10. Icons, buttons and other small inline images should NOT use a border or vertical spacing.
   • The Vertical space maintains the correct proportion between the graphic and the text after it.
8. Leave the other fields blank. Click Save. The image is attached.
9. If you need to resize the image, highlight the image and resize it by dragging it in or out. Images should not exceed a width of 650px.

Top

Decorative images

A decorative image is an image that "serves no specific purpose, meaning that they are not meant to convey any meaning or important information" (Siteimprove). Decorative images should use NULL or empty alt text. This is so that a screen reader or other assistive technology will skip past the image. An example of decorative art can be seen in the Google File Stream article, below the In This Article heading.

In most cases, when you are attaching an image to an article, you are doing so to illustrate the instructions of a step. Depending on the instructions, alt text may or may not be appropriate. If you are not sure whether to use alt text (or an image caption), use the Web Accessibility initiative alt text decision tree to decide.

Top 

Marking up images

Use a red arrow and red boxes to indicate specific sections of an image, unless there is a contrast issue. See the image below for an example.

Do NOT put text instructions in an image. If you must put instructions or text in an image, those instructions must meet accessibility requirements. 

Top 

Images with text

Due to the nature of our work, many images are going to have text in them such as Excel or Google Drive sheets. Images with text are NOT accessible. The text in an image cannot be read by someone using a screen reader or other assistive technology. Readers with low vision may have trouble reading text if it becomes pixelated when magnified.

However, it may be impossible to avoid using an image with text. For that reason, we have various methods to correct this issue:

• Hyperlink to sheets.
• Conveying important text information in the text instructions.
• Image captions.
• Alt text.

If feasible, hyperlink to the sheets instead of using screenshots with extensive, inaccessible text. Whenever possible, convey the image's text information in text instructions. If that is not possible, use image captions and alt text to share context. If you are not sure whether to use alt text (or an image caption), use the Web Accessibility initiative alt text decision tree to decide.

Top 

Icons in sentences

When using an icon in a sentence, there are some things to consider.

1. If the icon includes consistently visible text it should precede the icon.
2. If the icon only contains text when hovering over it with your mouse do not include it in the sentence.
3. Do not include a border when using icons in a sentence.

NOTE: The icon name should be included in the alt text and the icon name verified by the vendor in their documentation, by hovering over it, or clicking it.

Here are examples of each scenario.

1. Click the green    button at the bottom of the window.
2. Click the Launch Editor button at the top of the page next to Save button.

Word usage and consistency list

The Word Usage and Consistency List article is a living list of guidelines for specific and frequently used services and technical terms. It exists to provide consistency and coherency with how Knowledge Management refers things.

Top