DAR KB Style Guide

Overall Considerations

• Keep content SHORT whenever possible
  We always want to explain everything, and write full documentation. These full guides almost never get used, sadly. What gets consistent use are answers to people's questions.
• Create articles that will show up when someone searches for a thing, and that they will recognize as being the result that they were searching for.
• Focus on the steps to accomplish tasks rather than paragraphs about a topic.

Style Specifics

Titles

• A good naming convention is to start with the topic category, followed by a colon, followed by an action-oriented subtitle that your audience will recognize when they pull this up in a search result. For example: Events: Adding the Payment Widget.

Headings

• Use Heading 2 as your largest heading in your articles. Heading 1 is used for the page title.

Body Text

• In general, follow Microsoft's Technical Writing style guide
• Lists
  • Use Numbered Lists for steps that people take in order
  • Use Bullet Lists for options people have
  • Make your lists Accessible to screen readers (here's how)
  • Do not end list items with punctuation unless the lack of punctuation would ruin the meaning of the list
• Use Bold rather than quotation marks to indicate the button, heading, etc that people need to find in order to accomplish the action at hand
• Do NOT use Bold or text colors for emphasis except in the most dire circumstances.
  The more we highlight the important text with fonts and colors, the less people can distinguish between the steps they should take and all the other words on the page
• Use the Less Than symbol > to move people from one menu item to its submenu items

Links

See our Accessibility guide for more about making links work well.

Images

• See our accessibility guide 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. In the Protocol box, select <other>
4. In the URL box type tel:[phone number]