Knowledge Base: KB Style Guide Checklist

Summary

This Style Guide provides a list of items to check in knowledge base articles.  Confirm these items every time you review or create an article. This article is for anyone reviewing or writing articles in the TeamDynamix (TDx) Knowledge Base (KB).

Note:  When you create a new article, there are no tabs until you Save the article.  The Body field contains the content of the article and will be saved by itself on the Content tab.  All the other fields on the new article screen will be saved to the Settings tab.

For help with the KB editing tools, see also article - Knowledge Base: Using the KB Editor toolbars

 

To Review on Content tab

Topic or Objective – one per article  

Article may include more than one task to achieve the objective.  For example, different tasks for different operating systems to achieve the same objective, or an objective that requires several independent tasks for completion.

 

Summary – one or two sentences describing the purpose of the article

  • What action(s) on what service/software/app the article covers, 
    • Specify operating system (OS) or platform if appropriate,
  • Who the content applies to (e.g. students, employees, all windows users, parents, campus visitors, etc.), and
  • Why someone might need/want to read this article, or What will it do for me?

 

Formatting – default font and size 

  • Black, default Font, default Size – this may need to be changed on older articles.  See Knowledge Base: Setting Default Font and Size
  • Numbered steps, NOT an ordered list.  Manually type out and bold the step numbers, e.g. 

Step 1 – Do this first

Step 2 – Do this next

  • Use Bold  to highlight what to do, the name of an object you are opening, clicking, or selecting; to instruct user to perform an action.
    • Also use bold to mark something that is more important, to draw the eye quickly to those words.
  • Use Italics to mark words user should be looking for on the screen, like the name or path of an object or application. Use italics to mark what a user will see as the result of an action. Sometimes also bold or in quotation marks.

 

Headings – Heading 2 or smaller

  • Title – do NOT repeat the title in article Body text, title goes in the Subject field only (on Settings tab of existing articles)
  • Do not use Heading 1 style in the Body of the article. 
  • Sections – use Heading 2
    • Follow title capitalization for Section headings - major words capitalized
  • Subheadings/Sub-sections – use Heading 3, Heading 4, etc.
    • Capitalize first word. May use title capitalization or not, depending on context

 

Links – Meaningful link text that opens in new tab/window

  • Use meaningful words for the visible link text - may need to re-word sentences so text of link describes the landing content.
    • For example, say "See detailed instructions in Article Title as hyper-link" instead of "Click here for detailed instructions."
  • Set Link Target to New Window (_blank) on the Target (second) tab of the hyperlink dialog box,
  • Edit or remove any out-of-date links that point to bad or missing pages.
    • If the link points to an Archived article in our own KB and there is a Replacement Article, update the link to point directly to that Replacement instead.

 

Screen shots – to enhance text instructions

  • Use screen shots sparingly, only to enhance text.
    • See instructions below for using Images in KB articles.
  • Consider brief Videos as another option to enhance text instructions.
    • Include YouTube videos with the dedicated Embed YouTube Video button (right-hand end of the middle toolbar in the KB Editor)
    • [Coming soon: a separate article on how to embed Kaltura or Vimeo videos]
    • Videos from other sources might be able to be embedded. Submit a ticket using the Request TeamDynamix Services button on the TeamDynamix Application Administration Service page - choose Request Type of Knowledge Base request. Specify the video source and specific video sharing link you want to embed along with any other details you can provide.

 

Images – keep accessibility in mind

  • Explanation or instruction step goes above the image
  • For full-size images (uploaded or hyperlinked):
    • Include Alternative Text describing the relevant part of the image
    • Lock aspect ratio and use common width(s) for all (or most) images within the article.
      • Keep images at or smaller than their original size. They will look fuzzy if they are bigger.
      • To revert to the original size, click the circle arrow "refresh" icon next to the padlock
    • Width 300 or smaller works on mobile phones, portrait mode.  Wider needs landscape mode to be readable.
    • Width 700 is the largest we use in our KB.
    • Black border size = 1
    • Keep the Alignment option as <not set> or else the text will not wrap properly. 
  • For thumbnail images (pasted into article): 
    • Add text immediately below thumbnail saying, in italics:  Click for full-size image
    • Edit default Alternative Text to describe the relevant parts of the full-size image
    • Never adjust any other settings for a pasted image.
  • Add a blank line below the image for visual space before the next step.

Note: This Images section is also in article - Knowledge Base: Fixing fuzzy or small KB Images

 

Tables – keep accessibility in mind

  • Include Heading Row and/or Heading Column for assistive technology
  • [Coming soon: a separate article on working with Tables]

Back to top

 

To Review on Settings tab

Title (Subject) – topic of the article

  • Do NOT repeat the title in article Body text, title goes in the Subject field only
  • Follow title capitalization – major words capitalized, small words ("of", "the", "in", "on", etc.) in lower case
  • Prefer only one “topic” per article, but this is a bit fuzzy.  If your title has the word "and", consider if it should really be broken into separate articles.
  • Begin title with the name of the service and a colon ( : ), then specific words depending on the article type as listed below
  • If the article applies to only some campuses, specify those at the beginning of the article title.

Title Guidelines for specific article types

  • How To article –  
    • Begin with ServiceName:  , then an "ING" action word, explaining what the reader will learn how to do in that article, after the colon  
  • Informational article – 
    • Begin with ServiceName:  , then "what" the article focuses on after the colon
  • Frequently Asked Questions (FAQ) article – 
    • Use ServiceName: Frequently Asked Questions (FAQ) if it's about the entire service
    • Specify focus of FAQ if it’s not about the entire Service, like ServiceName: Specific Topic (FAQ) 
  • Troubleshooting article (rare) – 
    • Begin with ServiceName:  , then the problem user is trying to solve after the colon
    • May say “Troubleshooting” in the title

Example article titles

 

Article Summary – 500 character limit on the Settings tab 

  • Displays on search results screens or when looking at the KB Category containing the article. 
  • May copy Summary from article Body.  Edit if necessary to fit within 500 characters.

 

Tags – appropriate to topic

  • can only contain letters, numbers, or a dash (hyphen)​​​​​​
  • ​no spaces or special characters allowed
  • use a dash (hyphen) between words

 

Next Review Date – normally 6 months from today

  • Articles need to be reviewed on a regular basis
  • Next Review Date may be tied to cyclical activity within the department, such as reviewing certain articles before Back to School or end of Fiscal Year.
  • Reports are available to assist you with finding articles up for review
  • Notify Owner of Review Date is checked if not using article review reports. Owning group is notified 14 days before the review date.
    • The notification is logged as an Update in the article History (feed), obscuring the last date that any content updates were made.
    • If possible, using article review reports is preferred.

 

Owner – is a TDx Group, not an individual person

  • Notify Owner on Feedback is checked

 

Applicable Institution(s) – appropriate boxes are checked

  • If you are not sure which institutions this article applies to, check with your supervisor or a subject matter expert for that article.

 

Archived Articles - choose a replacement article if one exists

  • If an appropriate replacement article exists, add it on the Settings tab of the Archived article
  • Readers will automatically see the replacement article any time they follow a link to the old, archived article.
  • This feature was added in June 2022 (TDx ver. 11.3), so articles Archived before that time may not yet have any replacement specified.

Back to top

 

KB Templates

  • We have full Article Templates, but also smaller Section Templates.
  • If using a template, the template contents will be inserted wherever the cursor is at that time. 
  • See Sample articles using KB templates to know what you’ll be getting if you choose that template.

Back to top

 

Further Readings

Sample Articles using KB Templates

Knowledge Base: Fixing fuzzy or small KB Images

Knowledge Base: Setting Default Font and Size

 

Need additional help?

Submit a TeamDynamix Application Administration ticket - use the Request TeamDynamix Service button then choose Request Type Knowledge Base request.

Visit the Technology Help Desk Support page to locate your local campus contact information or to submit an online technology support request. For password issues you must call or visit the Help Desk in person.  

 

 

 

 

 

Print Article