General Writing Guide: UConn Knowledge Base

The Knowledge Base is a collection of information that offers technical support to the UConn community.  ITS faculty and staff can contribute by creating and editing articles within Confluence, an online workspace.

When adding or revising content in Confluence, it is important to follow general writing guidelines and maintain professional, uniform language across the resource.

General Writing Guidelines

Title: Keep titles clear, brief, and specific. Start with the action that the article is offering support for first: for example, this article is titled, “Contribute to the Knowledge Base” instead of “Knowledge Base Contributions.” This streamlines readers' experiences navigating the sidebar, making each article more accessible. For support on adding titles and headings to your article, visit: Content Structure Guide: UConn Knowledge Base.

Opening: The first sentence of your article should provide context to the reader. If the article topic is a system, service, software, application, or device that may not be familiar to the general public, define it in the opening sentence (reread the opening paragraph of this article for an example).

Login information: If the article topic is a website or system that requires a login, indicate the login credentials needed at the top of the page. It can be helpful to include this in an information panel to quickly direct readers to a login portal (for an example, revisit the top of this page).

Do’s

• Use “UConn” or “university” instead of “organization.”

• Add a period at the end of a numbered step.

• Use task-oriented, plain language (e.g., Log in on the Single Sign On screen with your NetID and NetID password).

• Title images that you add to the article.

• Provide a link or contact information for additional support when possible (for an example, see the bottom of this page).

• Insert a table of contents when including multiple support topics in an article (for an example, see the “in this article” list at the top of this page).

• Use the embedded templates when including bulleted lists and numbered steps.

  Open

  

  Use templates to create numbered or bulleted lists

Don’ts

• Don’t underline important points. Some readers may mistake it for a link. For detailed instructions on how to format text in an article, visit: Format Guide: UConn Knowledge Base.

• Don’t use overly technical descriptions (e.g., Authenticate into CAS with your NetID credentials).

• Don’t dump links to other pages or websites without context. Treat an outside link like a guest in your article - introduce it and make it feel welcome. For example: if you need additional support on directing readers to outside links, visit: Links Guide: UConn Knowledge Base.

• Don’t use colored texts to emphasize information. Instead, use the info panel tools to draw attention to important points. For support on using info panels, visit: Macros Guide: UConn Knowledge Base.

• Don’t paste images directly into the article. You must use the embedded “add image, video, or file” tool from the tool bar for the image to insert properly. For support on adding images, visit: Images Guide: Knowledge Base.

  Open

  

  Add an image from the Confluence toolbar, not from your clipboard

Using Technical Terms 

If you are using a term that may not be familiar to all readers, it can be helpful to include an explanation.  If an article is intended for use university-wide, ask yourself: would a high school student be familiar with this term? If the answer is probably not, then consider adding a simple definition. 

Use plain language that’s easy to digest for readers with little to no technical knowledge. Here are some examples (feel free to use them):

• VPN: Virtual Private Networking (VPN) software that creates a secure connection between your off-campus computing device and the campus internet network. 

• Encrypted: information concealed with code so that only people with a password can decode it.

• Local files: files downloaded onto the computer that you can access without an internet connection. 

• Cache: A storage solution that temporarily stores the data you access on websites and applications, so that it loads faster when you access it again.

• Extended desktop: multiple monitors that work together to behave as one screen. 

• Operating system (OS): the primary software that manages a computer (ex. iOS, Windows, Android, etc.). 

• Internal disk/drive: A physical storage device that is built into a computer. 

• External disk/drive: A physical storage device that you can connect and disconnect to a computer.

• Data corruption: When data becomes altered, unusable, or inaccessible due to errors in computer data. 

• Web client: A web application that does not require installation and is accessible via internet. 

• Browser extension: a tool that attaches to your internet browser to customize or increase your capabilities while using the browser. 

Try different strategies to define a technical term:

• Use context to imply the meaning. For 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. For 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.”

Useful Links:

Format Guide: UConn Knowledge Base.

Content Structure Guide: UConn Knowledge Base.