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.
Article Overview
1.0 Article Content
The content of the articles should be clear and concise. Content should be geared towards a lay audience with minimal technological experience.
1.1 – Article Topics
Articles should focus on a single topic of interest to the intended audience of the Knowledge Base.
How-to Articles
For how-to articles, the topic will be task-oriented. Articles that contain more than one task should be broken up into two separate articles.* For example, an article such as "Changing and Resetting your Google Password" should be broken up into two articles titled "Changing your Google Password" and "Resetting your Google Password." This is done because changing a password and resetting a password are two separate tasks with two separate sets of instructions.
We would rather have more short and descriptive articles than have longer articles that cover multiple topics.
Troubleshooting Articles
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 (e.g., "Cannot Connect to UConn Secure" or "Wifi Adapter 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 (e.g., "HuskyVision Troubleshooting").
Informational Articles
Informational articles should provide a brief overview of a topic and help orient readers so that they can understand a concept and seek more informed assistance on an issue.
1.2 – Article Titles
How-to Article Titles
For how-to articles, we start with a gerund – a verb with the suffix "-ing" that is used as a noun (e.g., "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 Emails..." or "Saving Emails..."
Troubleshooting Articles
For troubleshooting articles, the title should be the problem the user is trying to solve (e.g., "Printer is Flashing 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 have "overview" at the end of the title (e.g., "G Suite Overview").
Titles should never be presented in the form of a question.
For example, if you were writing an article about Webex Webinars attendees, use a title like, "Managing Webex Webinars Registrants" instead of "How Do I Manage Webex Webinars Registrants?"
1.3 – Labels
All articles must include labels (or metadata) – keywords that are related to the topic of the article. Labels support an effective search and group related articles together.
1.4 – Summary Statements
Article summaries are meant to help users quickly assess the relevance of the article for their problem or question. Article summaries should include two things: (1) who the article is intended for and (2) what functionality the user can gain from the article.
EXAMPLE 1: "Students can set up their G Suite account."
EXAMPLE 2: "Students, faculty, and staff can resolve issues they experience when connecting to UConn Secure."
Subsequent sentences in the summary should follow a hierarchical structure with the most important information put first.
1.5 – Links
Linking to Other Confluence Articles
Topics may come up while writing that are not familiar to the user. If 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; embed the link 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.").
To insert these links to your article,
Click on the link icon in the toolbar at the top of the edit window.
Click Search.
Enter the name of the article that you want to link.
At the bottom of that window, you can change how the link appears in your article by altering the link text.
Click Insert.
Avoid using phrases such as "Click Here," "Read More," or "Learn More" as the sole link text. These phrases do not provide any context for users with assistive technology, such as a screen reader user.
Linking to Websites Outside of Confluence
To link to a page outside of Confluence, like netid.uconn.edu, insert the link without the "http://" by altering the link text.
Use the actual link if the link is small, like email.uconn.edu. For longer links, change the link text so that it takes up less space on the article and provides context for assistive technology users.
To insert these links to your article,
Click on the link icon in the toolbar at the top of the edit window.
Click Web Link.
Enter or copy and paste the link into the Address field.
If needed, you can change how the link appears in your article by altering the link text.
Click Insert.
1.6 – Note/Info/Tip/Warning Macros
When inserting these macros, add the name of the macro (Note, Info, Tip, or Warning) under the "optional title" section of the macro edit window.
To access the macro edit window,
Left click on the macro.
Click edit.
See below for examples of what each Macro title should look like.
Do not mix the macros and their names, like, for example, adding an info macro and titling it "Note."
2.0 Article Formatting
The formatting of the articles should enable readers to skim the article easily and assess relevance.
2.1 – Bold Words
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."
2.3 – Headings
All headings should specifically describe what is in that section of the article. Usually in how-to articles, headings are a re-iteration of the article title. (i.e., if the article title is "Accessing Email in Windows," then the heading should be the same thing instead of something like "Accessing Email" or "Email in Windows." When applied consistently, headings help readers skim content and understand the article's organization quickly. It also enables macros within our KB to work correctly.
All article titles should be formatted as Heading 1.
All second level headings within the article, which mark the different sections within an article (e.g., Article Content), should be formatted as Heading 2.
Any subheadings underneath a level 2 heading should be formatted as Heading 3, then Heading 4, and so on.
To create headings,
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.
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
Numbers and bullets are an effective way to highlight key steps or information and break up blocks of text into meaningful units.
Use numbers for the steps of a process. Most how-to and troubleshooting articles have numbered steps.
Use bullets when listing items that do not need to be performed in a certain order or when simply providing information.
For consistent and easy formatting, use the toolbar to set these styles.
2.5 – Spacing
Use spacing to show what information belongs together and what is separate.
Insert one line's worth of space between steps and paragraphs.
For screenshots, leave no space between the image and text it illustrates, but do leave a space after the screenshot to distinguish it from the next step.
If you are trying to get lines of text to not have any spacing between them,
Place the cursor at the end of the preceding line of text.
Hold down the Shift key.
Press Enter. The cursor will shift to the next line without spacing.
3.0 Writing and Editing
3.1 – Language
The majority of the articles in the public-facing Knowledge Base are intended for a lay audience and should be written in plain language. Focus on the task they are trying to accomplish from their perspective and less on the technical language used to describe it.
EXAMPLE:
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.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:
Use context to imply the meaning.
EXAMPLE: With two-factor authentication, you will log into a service with your NetID and password and then verify your identify on a second device.
Explain the term in a clause following its mention.
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.
3.4 – Acronyms
On the first mention of an acronym, spell out the phrase, and then follow it with the acronym in parentheses. Once you have spelled out the phrase, you can continue to use the acronym.
EXAMPLE: Many services are behind the Central Authentication Service (CAS).
3.5 – Contractions
Avoid using contractions. We use a more formal tone, and contractions are more informal.
3.6 – Capitalization
Capitalize names and proper nouns (names used for an individual person, place, or organization). Words like 'faculty' and 'staff' should not be capitalized.
When writing instructions and referring to a word that is capitalized on the screen or device, you can capitalize the word to be consistent with the user's experience.
EXAMPLE: Go to the "My Settings & Devices" section to add a backup device.
If the words you are referring to on the screen or device are in lowercase, write the instructions accordingly.
3.7 – Punctuation
In general, use commas, periods, semi-colons, and hyphens appropriately. Avoid exclamation marks, which do not fit the tone of a Knowledge Base article.
One common punctuation mistake is to separate two complete sentences with a comma. Make sure to use a period or join with a comma and conjunction.
Mistake: Enter your full name, then click OK.
Correct: Enter your full name. Then click OK. OR Enter your full name, and then click OK.
For lists and numbered steps, use a period if it is a complete sentence or completes a sentence started by the lead-in phrase.
EXAMPLE 1: Use a period.
You can verify your identity on the Duo Mobile App by
getting a Push Notification and selecting Approve.
entering the passcode on the app.
having the service call you.
EXAMPLE 2. No period
Stop by the front desk of the ITS Help Center for onboarding assistance.
Software access and installation
Virus detection and removal
Email set up
Wireless connectivity
Static IP assignment
3.8 – Standardized Terms and Phrases
The following words or phrases should be written or used in the following, standard ways when referring to them in your articles. For example, refer to the help center as the "ITS Help Center" or "Help Center," but do not refer to it as the "help desk" or "Husky Tech."
Category | Correct Term or Phrase | Do not use | Notes |
|---|---|---|---|
UConn Terms | UConn | UCONN, Uconn, uconn | |
NetID | netid, Netid, netID | use "NetID" for all instances, including within emails: NetID#####@uconn.edu | |
ITS Technology Support Center | Husky Tech, Help Desk, | ||
ITS | UITS | ||
Outlook | Office 365 Web Access | Office 365 Online | When referring to outlook and its services – "Office 365 Web Access" and "Outlook Desktop Client" are two different ways to access the same service called "Outlook." |
Outlook Desktop Client | |||
Giving Examples | (i.e., ________), or (e.g., _______) | (example, ____) | |
In Article Titles When Referring | "on Windows" "on Mac" | "in Windows/Mac" "for Windows/Mac" |
3.9 – Article Length
Articles should be kept short and require minimal scrolling. If there are multiple sub-sections in the article and the article is long (scrolling required), consider adding anchors to the subheadings to facilitate quick access to relevant information.
Keep paragraphs short - no more than four to five sentences. Use formatting elements such as bullets, numbers, and note sections to highlight relevant information and to break text up into units that are easy to follow. (See Numbers and Bullets in the formatting section.) Organize and separate sections with subheadings. This will help readers skim the content and find the desired section. (See headings in the formatting section.)
3.10 – Macros
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.
For more information about macros, see Macros: Understanding and Inserting Dynamic Content (OLD).
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.
3.12 – Keyboard Shortcuts
There are a number of helpful keyboard shortcuts that will make your article writing process faster if you would like to use them.