All articles in the ITS Knowledge Base must follow a consistent style and tone. This style guide is intended to provide a set of standards for content and formatting that should be applied to all articles. See Creating Articles for descriptions of various types of articles present in the Knowledge Base.
...
When you are instructing the reader to perform an action, such as clicking or entering, bold the word that corresponds to the on-screen buttons/clickable elements.
EXAMPLE 1: Click Save My Information to continue to the next screen.
EXAMPLE 2: Enter a personal email address (not your @uconn.edu) in the "Secondary Email Address" field, and click Save Changes.
2.2 – Quotation Marks
When instructing a reader to look for text on their screen, use quotation marks around the words they should be looking for.
EXAMPLE 1: Quotation marks should not be used when looking for text within a button/clickable element (see "Bold Words" above).
EXAMPLE 2: Un-check the box next to "Show Labels for Each Page."
...
Highlight the text.
In the toolbar, click the dropdown menu that by default says "Paragraph."
Add headings as you see fit. Ensure that the heading style is appropriate for the level of your heading.
| Note |
|---|
All headings, regardless of type (i.e., Heading 1, Heading 2, Heading 3, etc.) should follow standard capitalization practices for titles – such that the major words in the title are capitalized. For example, a heading should read "Helpful Functionalities of the Confluence Editing Window" instead of "Helpful functionalities of the confluence editing window." |
2.4 – Numbers and Bullets
...
Use task-oriented, plain language: Log in on the Single Sign On screen with your NetID and NetID password.
Avoid an overly technical description: Authenticate into CAS with your NetID credentials.
3.2 – Images
Images can impart a lot of information quickly. However, they can become outdated quickly and add a lot of length to an article. Use an image when it clarifies a more complicated action or conveys a lot of information quickly. When considering how and when to use an image, follow these guidelines:
When to Use Images
Use images when the instructional steps are complex or several actions are incorporated into a step or into many steps.
Ask yourself: Is the image really necessary? Can I just use plain text to get the same message across?
Avoid using images of text when possible.
Consistency of Image Capture Method
All KB contributors should be using a standard image capturing method to allow for consistency among the KB articles.
For PC, use the snipping tool. Make sure you take the snip at a high enough zoom so that the resolution is maintained once you place your image into the article. Add callouts as necessary in PowerPoint (see section 4.2 of this style guide).
For Mac, use the print screen function and crop the image. Make sure that the section you want to crop is not too small and that it will retain a high resolution when you input the image to your article. Add callouts as necessary in PowerPoint (see section 4.2 of this style guide).
Image Size
Screenshots should be big enough to clearly display image contents without having to click on or enlarge the image.
Ensure that you size the image in Confluence so it does not extend past the text around it, and so it is not too small either. Judgement is key here.
Image Borders
Images, especially those with a white background, may get lost on a white page. Add a black border around all images.
Image Position
Images should always be below the explanatory text that references the image.
Alternate Text
Use descriptive alt text when you place an image into your article and have not adequately described above the image what the user is supposed to gain from it.
3.3 – Definitions
If you have to include a technical word to make sense of the topic, find a way to define it for the reader. Some strategies include:
...