Content Structure Guide: UConn Knowledge Base

Owned by Lily Cox (Deactivated)
Last updated: Jul 29, 2024 by Dan Jakubiak
3 min read

The content of Knowledge Base articles should be clear, concise, and geared towards an audience with minimal technological experience. 

In this article:

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 NetID Password" should be broken up into two articles titled "Changing your NetID Password" and "Resetting your NetID 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. 

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

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,

  1. Highlight the text. 

  2. In the toolbar, click the dropdown menu that by default says "Paragraph."

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

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. Organize and separate sections with subheadings. This will help readers skim the content and find the desired section. (See headings in the formatting section.)