Style Guide

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

Once articles are submitted, they will be reviewed and approved based on the content and formatting guidelines outlined in this style guide.

Audience

This article is intended for staff, faculty and student employees who are submitting articles to the Knowledge Base. If the instructions apply to a specific user role with a system, such as an instructor, student, or administrator, the role should be mentioned.

Platform

TeamDynamix

Contents

Category

The category field defines the broad category 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.

Do not repeat the subject in the body field or it will appear to be duplicate information in the KB dashboard.

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:

  • Effective
    • Set Up VPN in Microsoft Windows 10
    • FAQ: VPN in Microsoft Windows 10
    • Quick Guide: Microsoft Windows 10
    • Getting Started: Information Architecture
  • Less Effective
    • Set up VPN.

Body

Step-by-step instructions should completely and concisely address the subject. For the IC community, assume basic technical knowledge, such as how to open a program or locate a menu item. Instructions should be written so an audience with various levels of technical expertise can follow with minimal assistance.

Format the body of the article as follows:

  • The first paragraph is a summary of the topic.
  • "Audience" title, using the Heading 2 format, followed by a summary of intended audience members. (e.g. "This article is intended for [students], [faculty], [staff], [alumni], [retirees], [affiliates], [visitors] and [public].")
  • "Platform" title, using the Heading 2 format, followed by a summary of the platform. The platform should be more specific than broad. Platforms include but are not limited to:
    • Operating Systems: Operating systems should be prefixed with the manufacturer, and, if applicable, version number or name (e.g. Microsoft Windows 10, Microsoft Windows, Apple macOS High Sierra, Apple macOS, Apple iOS 10, Apple iOS, Google Android Nougat, Google Android 7, Google Android).
    • Device: Devices should be prefixed with the manufacturer (e.g. Dell Latitude, Apple MacBook Pro, Apple iPhone, Google Nexus, Samsung Galaxy S8). Generic topics can be indicated with the device type (e.g. laptop, desktop, smartphone).
    • Product Name: Major products should be prefixed with the manufacturer (e.g. Microsoft Office 365, Microsoft Word, Adobe Acrobat, Adobe DC). Minor products, or products that are referenced without the manufacturer name, should not be prefixed (e.g. LinkedIn Learning, Zoom).
    • Company Name: The company name generally should not be used unless the topic covers all products, devices or operating systems offered by the company (e.g. Microsoft, Apple, Google, Dell).
  • "Contents" title, using the Heading 2 format, followed by a table of contents if the guide contains a significant number of subsections or if the guide is of significant length.

Tips

  • Write in complete sentences, including a subject, verb and object.
  • Use simple language, omit non-essential words and avoid technical jargon wherever possible.
  • Actions should be italicized.
  • The noun receiving the action should be bold text.
  • Text that needs to be entered into a textbox should use the Courier New font.

Example

  • Effective: Select Set VPN Server and type vpn.ithaca.edu into the textbox.

Tip

  • Use active voice and present tense.
  • Make instructions clear, direct and simple by using active voice and present tense.

Example

  • Effective
    • The computer displays the Print screen.
  • Less Effective
    • The Print screen is displayed by the system.
    • The system will display the Print screen.

Tip

  • Address the user in the second person (you, your) to make it clear who must complete the action.

Example

  • Effective
    • Enter your Netpass username in the Username field and click OK.
  • Less Effective
    • Type your Netpass username at the log-in screen and click the OK button to continue.
      • Your Netpass Username in Username field.

Summary

The summary field should contain a short description of the article that 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 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, -)

If there are tags that are already in use, use the already in use ones as opposed to creating your own.

Examples

  • Operating Systems: Microsoft, Windows, Apple, macOS, High_Sierra,  iOS, Google, Android, Nougat
  • Device: Dell, Latitude, Apple, MacBook, MacBook-Pro, iPhone, Google, Nexus, Samsung, Galaxy, S8, laptop, desktop, smartphone
  • Company Name: Microsoft, Apple
  • Product Name: Microsoft, Office, Zoom, Adobe, Acrobat, DC, LinkedIn-Learning

Status

The status determines the visibility of the article. Not all users will see all options listed below:

  • Not Submitted: The article is a draft/work in progress and not ready to be submitted for approval to the Knowledge Base committee.
  • Submitted: The finished article is submitted for approval to the Knowledge Base committee.
  • 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. Every article must specify a review date, which should be 6 months after the article has been created.

Owner

The Owner field specifies the person who owns the article. It automatically defaults to the person creating the article, meaning you can manually change who the owner is. Only one person can be the owner. For our purposes, the owner should be Amy Thompson.

Formatting a Knowledge Base Article

  • By default, content entered in the body field is Helvetica in 12 point font.
  • The alignment must be left justified.
  • A double line or hard break (i.e. one blank line) must be entered between paragraphs and between pictures and text.
  • Use number or bullet lists.

Writing Step-By-Step Instructions

Step-by-step instructions must 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 actions or terms are recommended:

  • Check / Uncheck: For items where a check box needs to be selected. (e.g. Check Banana)
  • Choose: A menu option or a radio button. (e.g. Choose File>Print from the menu; Choose Apple)
  • Click / Double-Click / Right-Click: A button on the screen that is clicked upon by a mouse, pen or other input device. (e.g. Click OK)
  • Download: Usually hyperlinked to a file. (e.g. Download Adobe Acrobat)
  • Drop-Down Menu: A menu option. (e.g. Choose Adobe from the drop-down menu)
  • 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. (e.g. Press Windows Key+L to lock your screen)

Copying and Pasting Text

A Paste from Word icon.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 Icons

Icons can help convey that the body of text is a warning, notation or tip.

  1. Click the Font Awesome button on the TeamDynamix body toolbar.
  2. Click the search textbox.
    • For an warning, enter #cccc00 into the color textbox. Enter exclamation triangle into the search textbox. Click on the exclamation triangle icon (). 
    • For a notation or tip, enter #ffcc00 into the color textbox. Enter asterisk into the search textbox. Click on the asterisk icon ().
  3. Type a blank space after the icon appears.

Adding Website Links

A link icon.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.

Examples

Instructions

If the website is within or affiliated with Ithaca College:

  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.

If the website is not affiliated with Ithaca College:

  1. Click the Font Awesome button on the TeamDynamix body toolbar.
  2. Enter #0000ff into the color textbox.
  3. Click the search textbox. Enter link.
  4. Click on the external link icon ().
  5. Type a blank space after the icon appears.
  6. Click the Link button on the toolbar.
  7. Enter descriptive text into the Display Text field.
  8. Enter a link/URL into the URL field.
  9. Click the Target tab.
  10. Choose New Window (_blank) from the drop-down menu.

Linking to Documents, Videos and Audio Files

When linking to files, use a prefix with an icon, the name of the file, followed with the file type in parentheses.

  1. Click the Font Awesome button on the TeamDynamix body toolbar.
  2. Enter #0000ff into the color textbox.
  3. Click the search textbox. Enter:
    • File Archive () and File Zip () for compressed files,
    • File Audio () and File Sound () for sound files,
    • File Image () and File Picture () for image files,
    • File Movie () and File Video () for video files,
    • File Excel (), File Powerpoint () and File Word () for Microsoft files,
    • File PDF (), File Text (Inverted) () and File Word () for text files,
    • File Code () for code files, and
    • File () and Files () for generic files.
  4. Click on the icon of the corresponding file type.
  5. Type a blank space after the icon appears and type in a descriptive title.
  6. Highlight the descriptive title and click Link on the TeamDynamix body toolbar.
  7. Paste the file URL into the URL textbox.
  8. Click OK.
  9. Type a blank space after the URL and type () with the file type in between the brackets (e.g. PDF, DOC, ZIP).

Examples

Adding Images

An image icon.All images must be uploaded individually using the Insert/Edit Image upload. Images should follow these guidelines:

  • Alignment: Default (i.e. not set)
  • Dimensions: 600 or less. Maximum width is set at 600 pixels. When setting width, leave height blank to ensure proportional resizing.
  • Border: Leave blank
  • VSpace: 10
  • HSpace: Leave blank.
  • Alternate Text: See below.

The image pertaining to a step should be included in that step, appearing below the text. Separate the image from the text with a line break by pressing Shift+Enter).

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.

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 images must 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.

WebAIM contains a guide on  Alternate Text with numerous examples

  • It is not necessary to describe what actions the user should take (e.g. Click Next) if they are described in the accompanying instructions.
  • It is not necessary to indicate that the image is an image or a screenshot. (e.g. “This is an image of…”)

Examples

What type of device are you adding? Three choices are presented. The first option is a mobile phone and is recommended. The second option is a tablet, such as an iPad or Nexus 7. The third option is a landline.

  • Effective (see screenshot above): What type of device are you adding? Three choices are presented. The first option is a mobile phone and is recommended. The second option is a tablet, such as an iPad or Nexus 7. The third option is a landline. A Continue button is provided.
  • Not Effective (see screenshot above): This is a screenshot of a device addition.

Aaron Weinberg and Matt Thomas

  • Effective (see image above): Two smiling men in front of trees.
  • Not Effective (see image above): Aaron Weinberg and Matt Thomas

Instructions

  1. To add an image, click the Image button on the toolbar.
  2. Click the Upload tab.
  3. Click Choose File and upload a .jpg/.jpeg image.
  4. Enter alternate text (see below) into the Alternate Text field.

 

 

 

Print Article