Knowledge Base: Basic Style Guidelines

Accessibility

• Accessibility Article (link opens in a new tab) on our KB
• Web Services Group has a good guide to web accessibility (link opens in a new tab)
• Harvard has a good list of ways to write useful image alt text (link opens in a new tab)

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
  • do not end list items with punctuation
  • make sure your list is accessible (link opens in a new tab)!

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