All articles in the ITS Knowledge Base will 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. Please visit See Creating Articles for descriptions of the various types of articles that will be written in this knowledge base. This style guide pertains to all types of articles.present in the Knowledge Base.
Article Overview
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
...
Articles should focus on a single topic that would be of interest to the intended audience of the Knowledge Base.
...
Troubleshooting articles should focus on helping the user solve a problem that they are having. Similar to how-to articles, troubleshooting articles should focus on a single user issue (ie.eg., "Cannot connect Connect to UConn Secure" or "Wifi adapter shows there is no internetAdapter Shows There is No Internet"). If your article helps the user solve a single issue, but you need to ask multiple questions to either identify the problem or provide the user with a range of possible solutions, then you can include all of that content in a single article. Typically, these types of articles have "troubleshooting" at the end of the title (ie.eg., "HuskyVision Troubleshooting").
...
For how-to articles, we start with a gerund (that is, – a verb with the suffix "-ing" that is used as a noun , i(e.eg., "Adding a Mass Mail Account in Outlook"). Below are some guidelines for titling how-to articles.
- Pick one word for actionable things. Instead of titling an article "Archiving or Saving Emails..." title it "Archiving EmailEmails..." or "Saving EmailEmails..."
Troubleshooting Articles
For troubleshooting articles, the title should be the problem the user is trying to solve (ie.eg., "Printer is flashing red and won't printFlashing Red and Will Not Print").
Informational Articles
Titles for informational articles should make it clear what topic is covered in the articles. Typically, these types of articles will have "overview" at the end of the title or the title (ie.eg., "G Suite Overview").
| Note |
|---|
Titles should never be presented in the form of a question. For example, if you were writing an article about Webex Events attendees, use a title like, "Managing Webex Events Registrants," instead of "How Do I Manage Webex Events Registrants?" |
...
All articles must include labels (or metadata) , – keywords that are related to the topic of the article. Labels will help support an effective search and group related articles together.
...
Article summaries are meant to help to users to quickly assess the relevance of the article for their problem or question. Article summaries should include two things: (1) Who who the article is intended for and (2) what functionality the user can gain from the article.
...
Subsequent sentences in the summary should follow a hierarchical structure in that with the most important information for the user to assess relevance is put firstput first.
1.5 – Links
Linking to
...
Other Confluence
...
Articles
Topics come up while writing that may not be familiar to the user. If while writing you find that you mention a topic that may need further clarification and we have an article in our KB that clarifies that topic, please link that article to the page. Link the article so that it is embedded in the text that you are writing (e.g., "When you are Changing Your NetID Password, please follow the password guidelines"). You may need to change the way the link displays so that it syntactically fits with your writing (e.g., "You must have Password Recovery Options set up in order to reset a forgotten password.").
...
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."
...
- Highlight the text.
- In the toolbar, click the dropdown menu that by default says "Paragraph."
You can choose to add headings as you see fit. Ensure that the heading style is appropriate for the level of your heading.
Note title 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
...
Instead of using a layout table for information, consider using the Columns macro. When screen reader users encounter a table with data cells coded using <td>, they expect to also hear information about table headers (<th>). Layout tables do not have table headers. Typically, in HTML, a layout table could be assigned the role="presentation" so that screen readers will read the content of layout tables as text, rather than as a table; this is not possible through Confluence. Because this is not a function Confluence supports, it is better to use the Columns macro to visually style the page. When using the Columns macro, you will be asked to input the column width in pixels or in percentages. Use percentages so that the column content will be responsive. Add additional Columns by inserting additional macros below the initial macro.
4.6 - Color Contrast
Making text high enough contrast against its background is vital for users who are colorblind or may have low vision. These users may not be able to distinguish text if it is too similar in brightness to its background. One good tool to check for color contrast is the Colour Contrast Analyser. To download Colour Contrast Analyser, click the Download button and choose CCA-Setup-3.0.1.exe. Text should meet a ratio of 4.5:1 between the foreground and background colors. This will cause the WCAG 2.1 results heading 1.4.3 Contrast (Minimum) (AA) to have green check marks. If the results show a red x, then the contrast is not high enough and you will need to adjust the text or the background's color.
...