Knowledge Base: Basic Style Guidelines

Accessibility

Articles

  • Keep things focused, brief, and on a single topic. Articles will get attached to tickets, so having a client scroll through long articles when all they need is one thing will be frustrating
    • Keep paragraphs to a minimum and concentrate on the steps for accomplishing a task, typically in list form
  • Write for the web (link opens in a new tab)! Keep in mind that people will read these articles on their phones.
  • You can create "guide articles" that walk people through several single-topic articles. Add "quick start guide" to the title (e.g. "Zulu Softphone: Quick Start Guide")
  • You can also group single-topic articles using "Related Articles" or by creating a Topic
  • Avoid a long introductory paragraph, and only include one if the article needs a brief explanation for context

Article Formatting

  • See our accessibility page (link opens in new tab) on headings.
  • Use Headings 2 and down. Heading 1 is the same as the page title.
  • Only use bold text for the most important words in the article, like things that people are clicking on, or important key words.
  • Referring to Buttons, links, tabs, settings, etc
    • Use bold to refer to the text people will click on
    • Use a "less than" symbol > to move people from one menu to the next (e.g. Click Settings > Permissions)
  • Write instructions as numbered lists

Links

See our accessibility page (link opens in new tab) to see more about links.

Images

  • See our accessibility page (link opens in new tab) to see more about images images.
  • Use images sparingly. They are powerful, but...
    • they also need frequent review and updating
    • screens/menus  may not look the same for all clients
    • visually impaired clients will not benefit from images in the same way, even with alt text
  • Do use images on occasion to build context or help differentiate between buttons, but think carefully before doing so
  • Always name the image files before uploading so that the file name is useful, and include alt text

Phone Number Links

  1. Highlight the phone number text 
  2. Click the link button in the top of the editing window in the KB
  3.  Use the photo below to fill out the fields

Highlight phone number and click the link button. Display text is the phone number, Link Type is URL, Protocol is <other>, and URL is tel:[phone number]

Was this helpful?
0 reviews
Print Article

Related Articles (1)

ITS Knowledge Base Style Guide: Quick Start Guide
Overarching principles for Knowledge Base articles, plus specific decisions about naming conventions, use of images, etc that will help our Knowledge Base look consistent and predictable to our community.