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.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."
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.