Knowledge Base Article Style Guide

Style Guide 

TeamDynamix Knowledge Base (KB) articles should provide end users with clear and consistent instructions. 
This article is intended to assist in the development and styling of Knowledge Base articles.

Audience

This article is intended for Marist Staff, Faculty, and Students who have permission to create Knowledge Base articles. 

Environment

TeamDynamix

Category

The category field defines the broad area that the topic corresponds to. Only one category can be chosen.

Order

The value determines the order of all articles in a particular category. Articles are ordered first by this 
value and then by the subject. Pinned articles will always appear at the top of each subject list.

Writing a Knowledge Base Article

Writing content specifically for the web requires that the information be understandable, concise and consistent.
It also must be accessible to all users regardless of impairment.

Subject

The subject is the title of the article. Subjects can be prefixed to indicate that the article is an FAQ, 
Quick Guide, Getting Started or How To, as described below.  The name of the service, product, function, etc. should be included in the Subject.

Prefixes

FAQ: indicates the article is a list of frequently asked questions.
Quick Guide: indicates the article is a quick guide.
Getting Started: indicates the article is an introduction to a particular topic.
How To: indicates the article is a step-by-step guide to a particular topic.

Examples

  • How To: Set Up Duo Security on Your Phone
  • FAQ: Bringing Your Own Computer/Device to Campus
  • Quick Guide: Using ReAct for Password Management
  • Getting Started: Using Brightspace

Body

Step-by-step instructions should completely and concisely address the subject. For the Marist community, 
assume basic technical knowledge. Instructions should be written so an audience with various levels of 
technical expertise can follow with minimal assistance.

Tips

  • Write in complete sentences, including a subject, verb and object.
  • Use simple language, omit non-essential words and avoid technical jargon wherever possible.
  • Use active voice and present tense.
  • Spell out acronyms the first time they are used, and then put the term in parentheses showing how it will be written for the rest of the article.
    • Example: This is a Configuration Item (CI). The CI is . . .
  • Make instructions clear, direct and simple and assume that the reader is likely not very familiar with the subject matter. 
  • Address the user in the second person (you, your) to make it clear who must complete the action.

Summary

The summary field  is an additional bit of text that a reader sees before they select to open an article. It should capture the main ideas of the article content and help them decide if this is what they need or not.  The article summary is displayed in search results.

Tags

Tags allow users to find an article by keywords. The tags should be relevant to the topic and may include items such as operating system, device, company name, product name, and service. 

Tags can only contain alpha characters, alpha characters with numbers and dashes. (e.g. A-Z, a-z, -).  

Use tags that are already in use whenever possible as opposed to creating your own.

Examples

  • Operating Systems: Microsoft, Windows, Apple, macOS, iOS, Google, Android
  • Device: ThinkPad, ThinkCentre, MacBook, MacBook-Pro, iPhone, laptop, desktop, smartphone
  • Company Name: Microsoft, Apple, IBM, Lenovo, Hewlett Packard, Xerox 
  • Product Name: o365, Outlook, Zoom, Adobe, Acrobat, Banner, Brightspace

Status

The status determines the visibility of the article. Your role in the Knowledge Base will determine which of the options listed below will be available:

  • Not Submitted: The article is a draft/work in progress and not ready to be submitted for approval.
  • Submitted: The finished article has been submitted for approval.
  • Approved: The article is approved and is not visible in the Knowledge Base. Additionally, the "Published to KB" check box must be selected for it to be visible to the intended audience.
  • Rejected: The article is rejected and is not visible in the Knowledge Base.
  • Archived: The article is depreciated and is archived and no longer visible in the Knowledge Base.

Next Review Date

The Next Review Date indicates the date on which the article should next be reviewed for accuracy and relevancy. Every article must specify a review date, which should be 6 months after the article has been created.

Owner

The Owner field specifies the group that owns the article. It automatically defaults to the group of the person creating the article.  Avoid assigning articles to individuals. 

Formatting a Knowledge Base Article

  • Text should be left justified
  • A double line or hard break (i.e. one blank line) should be entered between paragraphs.
  • Use number or bullet lists.

Selecting an Article Template

Article Templates have been created for each of the Prefixes (FAQ, Quick Guide, Getting Started, How To) listed above.  Select the appropriate template from the Templates button on the toolbar based on the type of article you are writing. 

Writing Step-By-Step Instructions

Step-by-step instructions should be written as a numbered list. Second level lists should be bullet lists rather than number lists.

Separate each action as its own step. Some steps may require users to enter content into multiple fields or require additional instructions. In these cases, enter information as a second level list.

The following directives are recommended:

  • Check / Uncheck: For items where a check box needs to be selected. 
  • Choose: A menu option or a radio button. 
  • Click / Double-Click / Right-Click: A button on the screen that is clicked upon by a mouse, pen or other input device.
  • Download: Usually hyperlinked to a file. 
  • Drop-Down Menu: A menu option. 
  • Enter: Text must be typed into a field.
  • Log in or log in to: The act of entering information to access a system or account.
  • Open: An application or file.
  • Press: A key or other physical button. 

Copying and Pasting Text

To copy and paste into the body field, click the Paste from Word button on the toolbar, otherwise the formatting could cause the article to have incompatible styling.

Adding Website Links

It may be helpful to the user to include a website link to additional instructions or information. For accessibility purposes, provide a description of where the link goes.

Instructions

  1. Click the Link button on the toolbar.
  2. Enter descriptive text into the Display Text field.
  3. Enter a link/URL into the URL field.

Adding Images

All images should be uploaded individually using the Insert/Edit Image upload.

The image pertaining to a step should be included in that step, appearing below the text.

Including Screenshots

A screenshot is considered secondary to a well written body. Assume the reader can only reference written text and not images when developing content. A screenshot should only support the step they are associated with. Do not include a screenshot of an entire screen or application window.

Note that articles containing screenshots of user interfaces may need to be reviewed more frequently as these user interfaces change over time and the article will need to reflect the current state of these interfaces to avoid causing confusion when the article is viewed by customers.

Alternate Text

All images referenced in the Knowledge Base are subject to federal regulations regarding accessibility for anyone with a disability, such as those who are color blind, fully blind, or deaf. All need to contain either alternate text inputted into the image Alternate Text field or as information in text adjacent to the image or within the page containing the image.

 

Print Article