Knowledge Base Quick Guide

Description

The IT Knowledge Base is an internal and externally published repository of self-help solutions, instructional guides, and essential IT services and systems details. Articles should provide clear, accessible guidance. This guide establishes standards for content and formatting to be applied to articles. We suggest using the same terms for the same actions or objects throughout your article. Switching terms can confuse users and assistive technology.

Details

To enhance the article creation process, we recommend maximizing the screen for a more focused and efficient writing experience.

Basics

Writing Style

Write for the Customer

Think about your audience’s background, goals, and current mood. Ask yourself:

How experienced is the reader with this topic? Aim for a 6th to 8th grade reading level.
What’s the reader’s goal (e.g., completing a task or doing research)?
Is the reader in the middle of a task, in a hurry, or frustrated?

Voice and Tone

Use a clear, helpful, and conversational tone.
Speak directly to the reader using "you."
Keep the tone informal and straightforward.
Be concise, use short words and sentences, and skip unnecessary details.
Be specific, and avoid vague language and filler.
Use an active voice,

Enhance Content Readability

Avoid using technical jargon in articles intended for public or internal use unless necessary. If you do use it, explain in simple terms.
Target a 6th to 8th-grade reading level to ensure your content is clear and accessible to a broad audience.
Use common words like Use instead of Ulilize.
Keep sentences short and straightforward.
Put the action first.
List one idea per sentence or step.

Keep Paragraphs Short

Limit paragraphs to no more than three sentences. Use short, descriptive headings to make it easy to scan.

Formatting

Format

After completing or updating an article, ensure it follows the Normal (DIV) format for a clean, structured, and easy-to-read layout.

Highlight the article text or section text and select the Format dropdown
Scroll and Select Normal (DIV)

Actions

Use Select or Click instead of Tap. They are more inclusive and device-neutral terms that work across all input methods, such as mouse, keyboard, touchscreen, or assistive technology, making them accessible to everyone.
Use Visit when directing a user to an external site.
- e.g., Visit the ISU Web Page for more info.
Use Go to for internal navigation.
- e.g., Go to the Duo FAQ for more info.
Use Log in when you want a user to log in to something like external information.
- We discourage Log into or Sign In for accessibility-focused content.
Use Type when you are asking someone to input characters using a keyboard, as it is more descriptive.
Use Enter when you are asking a user to submit or confirm something like a password or number.

Abbreviations or Acronyms

Spell out abbreviations or acronyms the first time you use them, followed by the short version; then, you can use the short version for subsequent references.

e.g., Idaho State University (ISU) or Networking and Communications (NetCom)

Note: You can use abbreviations without explanation for well-known terms like API or HTML.

Hyperlinks and Emails

Embed the address within clickable text using a hyperlink and add a Font Awesome icon before the link.

e.g., Log in to MyISU with your ISU Username and Password, or Go to the DeviceNet article for more information
- Note: Use the appropriate Font Awesome icon based on the button's destination as necessary:
  - For external links, use the external link icon.
  - For internal TigerTracks links, use the link icon.

Images

We aim to discourage the use of images unless they are necessary. While images can enhance visual appeal, those that require a click to reveal content may not be fully accessible to users with visual impairments. Additionally, some screen readers may struggle to interpret the image.

Instructions

Ensure you use bold words that clearly describe the user's needs to enhance clarity and make the information easily identifiable.
Copy buttons or text exactly as shown. If a button is in all capital letters, be sure your article follows that format.
Do not use bold formatting for hyperlinks.
- For example, Click "Forgotten or Expired Password" or Log in to MyISU and click the University Resources link (far left).

Organizing Content and Structure Elements

Buttons

When writing articles, use "Select" instead of "click" or "tap." Select is a more inclusive and device-neutral term that works across all input methods, mouse, keyboard, touchscreen, or assistive technology, making it accessible for everyone.

Buttons: When describing a button, copy the exact wording; don't just type a Select button.
- Note: Use the appropriate Font Awesome icon based on the button's destination as necessary:
  - For external links, use the external-link icon.
  - For internal TigerTracks links, use the link icon.

e.g., Select the NEXT button or Select the Recover your Username or Reset your Password link

Note: If describing an action without a link, bold the action text. If the action includes a link, hyperlink the text without using bold formatting.

Bullets Guidelines

Bullets: Use for items where order doesn’t matter (unordered)
- Use the Disc (filled-in circles) for first-level bullets
  - Use the Circle for second-level bullets
    - Use the Square for third-level bullets
Numbers: Use for step-by-step instructions (ordered)
- Numbers from one to nine should be written as words, as they are easier to read.
- Numbers from 10 upwards should be presented as numerals
  - Limit each step to no more than two related actions

Numbered Writing Guidelines

Write out numbers 1–9

Use words for single-digit numbers (1 through 9) when they’re part of a sentence.
- Example: “You have three options.”
This helps screen readers pronounce the sentence more naturally.

Use numerals for 10 and above

Use digits for numbers 10 and higher.
- Example: You must complete this in 15 minutes.

Use commas in large numbers.

Make numbers easier to read by using commas:
- Correct: 1,000
- Not recommended: 1000

Avoid Roman numerals

Screen readers can misinterpret or mispronounce them.

Time & dates

Use full words for clarity:
- Preferred: “April 16, 2025, at 2:00 PM”
- Avoid: “04/16/25 at 14:00”

Currency and symbols

Always include a space and use full words where possible:
- Preferred: “$5” or “five dollars”
- Screen readers may not interpret “$” alone correctly without context.

Notes

Knowledge Base articles with notes should have the word Note: in bold, followed by the notes information.

Note: This is the preferred way to list a note in Knowledge Base articles.

Permissions

	Client	Contributor	Knowledge Manager	Service Manager
Add Articles
Address Feedback
Always Edit Articles
Delete Article Feedback
Delete Articles
Edit Archived Articles
Edit Owned Articles
Modify Article Templates
Modify Categories
Modify Shortcuts
Publish Articles
Review and Approve Drafts
Review Articles
View All Articles
View Articles Regardless of Status
View Knowledge Base

General Settings

Order / Pin

By default, Knowledge Base articles are sorted alphabetically within a category. This happens because the Order field is set to 1.0 for all articles, meaning no specific order is applied.

To customize the order, update the Order number for each article.
Assigning different values will position them accordingly, overriding the default alphabetical sorting.

Note: Do not check the Pin Article box.

Subject

To ensure clarity and consistency, the article subject (title) should follow this format:

Topic > Product (if applicable) > Audience (if applicable)

This structure helps users quickly find relevant information.

Topic – The main subject or action (e.g., How to Reset Password).
Product (optional) – The specific product or service (e.g., Microsoft 365).
Audience (optional) – The intended users (e.g., Students, Staff, Faculty).
- Examples:
  - Searching the ISU Class Schedule in MyISU for Students
  - View and Pay Fees in MyISU

Note: The above pattern covers most articles, but exceptions exist, such as FAQs. The FAQ template follows a Topic<FAQ pattern.

Example: DegreeWorks FAQ

Body

Templates

Templates in the TigerTracks Knowledge Base are a great asset because they make things faster, cleaner, and more consistent. In short, templates make the Knowledge Base more efficient and user-friendly!

Saves Time – No need to start from scratch every time; fill in the blanks.
Ensures Consistency – Keeps formatting and wording uniform, making information easy to follow.
Reduces Errors – Pre-set structures help avoid missing key details.
Improves Clarity – Well-designed templates make complex topics easier to understand.

Templates Available

Note: Select a template link below for more details.

Main Body (Please refrain from modifying the wording or formatting of the Main Body templates, as they are designed to maintain consistency.)
- FAQ Articles
- How To Articles
- Troubleshooting Articles
Supporting Elements
- Accordions
- Buttons
Customized Footers

Note: Submit a TigerTracks Announcement or Change Request to request a new template or a customized footer. Include the following information:

Title: New Knowledge Base Template Request
Detailed Description: Please provide your department name and details about the template you are requesting
Preferred Contact Number: Please provide your best contact number

Using Templates

Main Body Templates

Select a Template:
1. In the top menu bar, click on the Templates drop-down
2. Locate the 1-Main Body template section
3. Choose a template that fits your article best
Add a Description:
1. Scroll to the Description area.
2. Type a short summary or overview of what your article is about
Build Your Article:
1. Go to the Details section.
2. Start adding your content—headings, text, images, or any other elements relevant to your article.

Supporting Elements

Accordions

Note: Accordions should be used once per article. If you need to use them multiple times, you will need to edit the source code.

Select a Template:
1. In the top menu bar, click the Templates drop-down
2. Scroll to the Accordions section
3. Select an Accordion template that best suits your article
  - Note: The number after an accordion template indicates how many accordion sections it contains.

Buttons

Tip: To maintain the button’s formatting, first add your text, then delete the placeholder text—but don’t remove the button element itself. Avoid editing from the Edit Link area, which will break your two-line button layout.

Select a Template:
1. In the top menu bar, click the Templates drop-down
2. Scroll to the Buttons section
3. Select a Button template that best suits your article
  - Note: The number after a button template indicates how many buttons it contains.
Enter your Button Link:
1. Hover over the Button and right-click your mouse
2. Select Edit Link
3. Go to the Link Type drop-down and Select the desired option
4. Go to Protocol and Select the desired option
5. Type in the requested information
6. Click OK (blue button)

Footers (Optional)

Select a Template:
1. In the top menu bar, click the Templates drop-down
2. Scroll to the Footers section
3. Select a Footer template for your area

Source

Source code formatting refers to the HTML structure and styling used to keep articles readable, consistent, and maintainable. Editing the source code is an advanced feature, requiring training from a Knowledge Manager to ensure proper use and best practices.

Basic source code editing consists of:
- Accordion formatting when drop-downs are used multiple times

Justification, Font, Formatting, and Size

Justification

Knowledge base articles can be formatted using the menu's right, left, center, or justify icons to adjust text alignment for better readability and presentation.
You can modify margins automatically by using the increase or decrease indent icons.

Font

The font style in the TigerTracks Knowledge Base is preset. Do not change the font type.

Formatting

The header fonts are predetermined in templates. Please review each article section information individually to ensure it uses the Normal (DIV) format and preserves proper header formatting.

Headers

Heading 1: Article Subject (Title) Represents the article's main topic.
Heading 2: Main Body Templates Organizes content into clear, structured sections.
Heading 3: Accordion and Button Templates Subsections for interactive elements that improve readability and navigation.
Heading 4: Footer Templates Pre-designed sections at the bottom of a webpage or document, ensuring consistency across pages. Typically includes:

Normal (DIV)

Normal (DIV) is the standard font element for TigerTracks Knowledge Base articles. Please review all article sections to ensure they are appropriately assigned the Normal (DIV) format for consistent spacing.

Size

For clarity and consistency, we recommend keeping the default font size in your articles.

Styles

The Special Container is the only approved style feature used. It enhances visual appeal and separates sections in Knowledge Base articles.

Select the Styles dropdown from the menu and select Special Container
Type your special container text
Highlight the information
Select the Format from the menu and select Normal (DIV)

Font Awesome

Utilize Font Awesome icons to enhance transparency in steps; the library features thousands of icons you can include before each step to represent actions visually.

Select the Font Awesome Icon in the menu
Type a Search term to locate icons
Select your choice icon and click OK (blue button)

e.g., Log into MyISU with your ISU Username and Password or Click the Print button

Commonly Used Icons

Type Link for the internal link to TigerTracks supporting information
Type External Link Square for the icon to external supporting information
Type Check Square for the icon to use in tables
Type Ellipsis V for an icon that is popularly used for menus
Type Angle Down for the icon used for drop-downs
Type Print for the icon used for a printer or instructing a user on printing documents
Type Envelopes Bulk for the icon used for emails
Type Phone Alt for the icon used for phone numbers

Video

Videos or links to YouTube can be included in knowledge base articles to illustrate complex steps visually.

Select the YouTube icon in the menu.
- Paste your Embed Code or the YouTube Video URL and select your settings.
- Click OK (blue button)

Font and Background Color

List the answer here.

Anchors

Anchors are used to navigate between or link to specific sections in your article. You'll need to create and link the anchor to the supporting information to use anchors.

Place your mouse pointer on where you want the flag or bookmark to be and select the Anchor icon in the menu
Type an Anchor name and click OK (blue button)
- Note: A red flag will be placed so you can see your bookmark
Navigate to the area you would like your link listed
Select the Link icon in the menu
Locate the Link Type dropdown and select Link to anchor in the text
Navigate to the Select an Anchor field and By Anchor Name dropdown, and select your anchor

#anchor

Question: Type a question here

List the answer here.

Publishing Articles

List the answer here.

Contact ITS if you need additional assistance

0 reviews

Print Article

Updating...