All articles in the ITS Knowledge Base will 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. Please visit Creating Articles for descriptions of the types of articles that will be written in this knowledge base. This style guide pertains to all types of articles.
...
When you are instructing the reader to perform an action, such as clicking or entering, you should 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."
...
Create headings by highlighting the text. Then, in the toolbar, click the dropdown menu that by default says "Paragraph." You can choose to add headings as you see fit, just ensure that the heading style is appropriate for level of your heading.
| Note | ||
|---|---|---|
| ||
All headings, regardless of which type of heading they are (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
...
- 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. This will allow for consistency among the KB articles.
For PC → use the snipping tool. Make sure you take your snip at a high enough zoom so that the resolution is maintained once you place your image into the article. Add call outs as necessary in power point (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 call outs as necessary in power point (see section 4.2 of this style guide).
Image Size
- Screenshots should be big enough to get the point across without having to click on or enlarge the image. Users should be able to clearly view the image contents without having to click on it.
- Ensure that you size the image in Confluence so that it does not extend past the text around it, and so that it is not too small either. Judgement is key here.
- Image Borders
- Images with a white background will get lost on a white page, so consider adding a 1x black border around the image.
- Image Position
- Images should always be below the explanatory text that references the image.
- Alternate Text
- For images where there is explanatory text above the images
- In this case the explanation is already above the image, so to avoid redundancy we will use null alt text. To put in null alt text, just put double quotes "" into the alt text dialogue box.
- If your image requires the user to pay attention to multiple parts of an image, please use image call outs (see section 4.2 of this style guide).
- For images that do not have explanatory text above the image
- In this case, 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 the image.
- For images where there is explanatory text above the images
...
EXAMPLE: You can create an email alias (the portion of your email address to the left of @uconn.edu) that is different from the name originally assigned by the University.
...
Macros are visuals that dynamically organize your content and allow you to draw attention to aspects of your content that you want to have stand out to your readers. They are especially useful when you have a piece of information that is important for your readers but that does not fit into the rest of your article. Additionally, macros provide additional functionality to your articles, enabling you to do things like link pages, condense your content into accordion folders, insert page anchors, create and insert project timelines, and much more. See Macros: Understanding and Inserting Dynamic Content
3.11 – Spacing
Confluence headings have built in spacing, but make sure you take out as much space between sections as possible. This helps the reader flow through the information more easily.
...
Setting these cells as heading cells allows assistive technology like screen readers to associate data cells with their appropriate header cells. This is necessary for screen reader users to understand the relationship between data cells and header cells. Avoid images of tables, as none of the accessibility information will be available to users.
Table view must also be set to "responsive".
...