Skip to main content

IT Communications:
Resources

Knowledge base style guide for Rutgers IT

Rutgers IT knowledge base content should provide clear, accessible advice for members of the Rutgers community.

Guidelines

Here are some key guidelines:

  • Write clear, accurate, and up-to-date content.
  • Know your audience—in particular, whether you’re writing for a general audience or an IT audience.
  • Employ a user-friendly tone.
  • Avoid jargon.
  • Consult the Editorial style guide for Rutgers IT as needed.

Follow these guidelines for formatting when developing knowledge base content.

Titles and headings

Titles of knowledge base articles should usually include the name of the relevant service. This is important for helping users to find relevant content when searching for it.

  • Recommended: Storage space limits for OneDrive
  • Not recommended: Storage Space Limits

Use sentence case (capitalize only the first word) for titles:

  • Recommended: Instructions for connecting to RUWireless
  • Not recommended: Instructions for Connecting to RUWireless

Commands, menus, and UI elements

Use bold text (not quotation marks) when referring to menus, menu options, dialog boxes, commands, buttons, and other elements of the user interface. Examples:

  • Recommended: Choose Slide Show > Play from Current Slide to start your slide show.
  • Not recommended: Choose “Slide Show,” and then “Play from Current Slide” to start your slide show.

In addition, try to avoid terms that are specific to one device or interface; also avoid mentioning the specific UI element (i.e., that it’s a button). Instead, simply indicate what action a user needs to take. Examples:

  • Recommended: Select Save as and then…
  • Not recommended: Select the Save as button.
  • Recommended: Go to Tools > Spelling and Grammar, and then select Hide Spelling Errors.
  • Not recommended: Go to the Tools menu, click Spelling and Grammar, and then select Hide Spelling Errors.

Error messages

Enclose examples in quotation marks.

  • Example: If you receive an error message saying “Stop, you should wait to install Office 2016,” then consult the How to install Office instructions or contact the Help Desk for assistance.

Key names and keyboard sequences

Capitalize key names and keyboard sequences, as follows:

  • Ctrl+Alt+Del
  • Shift

For additional guidance on key names and keyboard sequences, consult the Microsoft Style Guide.

Links

Use meaningful links and avoid “click here” as a link. Avoid displaying URLs unless necessary.

Placeholder text

Use italics for placeholder text:

  • Example: Enter NetID username and password.

Procedures and sequences

Use arrows for procedures. Bold the step, but not the arrow:

  • Example: Choose File > Share > Send PDF.

If including the purpose of an action, do so before the actions:

  • Example: To share a document as a PDF, choose File > Share > Send PDF.

For a sequence of steps, use a numbered list.

Screenshots

Avoid overusing. For instance, do not use screenshots for obvious steps in a procedure, such as Next or OK. If needed, add labels, arrows, or notes to clarify the content of screenshots.

Resources used in preparing this document

Examples of knowledge base articles

Below, please find examples of Rutgers IT knowledge base articles that can be used for reference when creating new knowledge base articles.