Digital Content: Write Effectively

When you write knowledge, communications, and web content, you have to consider your audience. At the University of Minnesota, we have many potential audiences:

• Students
• Staff
• Faculty
• Alumni 
• The public
• All of the above, many of whom are English as a second language speakers and many of whom are not tech savvy

These audiences may have different needs but all of them need to understand content easily and quickly. The current standard is to write for a sixth or seventh grade level. Even if people can read at a higher level, simple is best for everyone.

Whether a piece of content is for the public or for internal use, your goal is to help the user:

• Find what they need
• Understand what they find
• Use what they find to meet their needs as quickly as possible

Although it is a guiding principle of writing to never assume someone's skill level or understanding, sometimes we create content for audiences that are highly technical. We rely on our partners to know who these groups are, and this knowledge may change our approach.

For example, if we're emailing a group of system administrators about a change, we might forgo providing certain context around the system itself and focus more on describing the change. This isn't a hard and fast rule, so use your best judgment. 

When in doubt, write it out. 

Additional Considerations for Comms

When we create communications (emails and announcements), we usually know who our audience is and can target certain user groups. However, sometimes the full impact of a technology change is unknown or too broad for direct communications. In these cases, we use the channels available to us to communicate broadly to the University community. These channels include MyU, Brief, other newsletters, and pop-up or in-app notifications. 

At the beginning of a communications project, we often complete an audience analysis to better understand how to target specific groups.

Additional Considerations for Knowledge

When we create knowledge articles, we usually know who our audience is and can set the knowledge to be available to certain groups/audiences. 

• Internal knowledge is knowledge whose audience has access to the TDX environment.
• Public knowledge is knowledge that's available on the Technology Help website. Most articles are available to the general public, but an article can be put behind login authentication (SSO) to only allow University affiliated audiences to view it.  

Additional Considerations for Website Content

Most pages are available to the general public, but a page can be put behind login authentication (SSO) to only allow University-affiliated audiences to view the content.

Use an approachable and friendly tone. Don't use unnecessarily big words or unnecessarily technical words. You want to maintain trust with the reader and empower them to use our resources for self-help.

Plain language is easier to scan and understand. Avoid big, multisyllabic words, a.k.a. $10 words. Use smaller and more commonly understood terms instead. Even experts and technical people prefer plain language.

For example, the word utilize is commonly spoken and written. But it means exactly the same thing as use. Use is a simple, one syllable, three letter word that everyone understands. 

We don't say end utilizer. We say end user. Actually, in OIT, we just say user in our written documentation.

Words should be short. Sentences should be short. Paragraphs should be short.

• Words should be familiar. 
• Sentences should be concise. 
• Paragraphs should have no more than a few sentences.
  • Believe it or not, one sentence paragraphs are acceptable. 

Fewer syllables, higher impact.

Additional Considerations for Comms

None

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

Jargon are special words or phrases used by a particular group and are often difficult for those outside of the group to understand. Jargon can be tricky. There are no hard and fast rules; much depends on the audience. When creating knowledge, communications, or web content, always assume novice exposure to relevant topics. 

Avoid jargon as much as possible, and replace any overly technical language with plain language alternatives. When addressing users directly, avoid referring to them as "users" and instead say "you." 

For example, instead of "Users may see updates to the application's user-interface," say "You may notice some changes to the way the home page looks once you've signed in." A good question to ask yourself is, "If someone who doesn't work in IT reads this, would they understand?"

Additionally, avoid using acronyms when possible. If they are needed, refer to Define Acronyms. 

Additional Considerations for Comms

None

Additional Considerations for Knowledge

• When creating an internal knowledge article, you have more latitude to use technical terms. 

  • However, not everyone has the same level of expertise with every technology. Avoid using jargon unless absolutely necessary.

• If the jargon is an acronym, define acronyms and abbreviations on first use. Refer to Define Acronyms. 

Additional Considerations for Website Content

None

The University uses many acronyms. We have them for physical things, organizational units, projects, processes, and more. We try to avoid using acronyms as much as possible. Only use them if the word or phrase appears repeatedly on a page or the acronym is well-recognized (we have a very high bar for what is considered well-recognized). We want to avoid abbreviations that are overly technical and, therefore, not user-friendly.

Often our jargon is acronyms, but not always. For example:

• RAM (Random Access Memory)
• NIC (Network Interface Card)
• VPN (Virtual Private Network)

The first time you use an acronym, spell it out and follow it with the acronym in parentheses.

• Examples:
  • Access Request Form (ARF)
  • Video Collaboration Storage and Hosting (VCSH)

When you need to use the term again, use the acronym. Do this consistently throughout your content.

You may begin a sentence with an acronym. It should be spelled out upon first mention on every page of a multiple-page draft.

Exceptions

Examples of well-recognized acronyms (i.e., acronyms that typically do not need to be spelled out):

• IT
• ID (internet ID)
• USB
• HIPAA
• URL

Additional Considerations for Comms

None

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

Good titles are short but descriptive. They should:

• Accurately summarize the content
• Use words users are most likely to search on
• Be 10 words or less (ideally)

Additional Considerations for Comms

Do not use acronyms in page titles, headings, or subheadings. Exception: Acronyms that are never spelled out, such as IT, can be used in those instances.

Additional Considerations for Knowledge

Use the active voice: Search, Create, Make, etc… for How to articles.

• Don't use How to; just start with an active verb, such as Create, Add, Use, etc..
• Do not start a subject with "How to…"
• Example:
  • Reset your Internet ID Password with Technology Help

In our environment, depending on the article type, start the title (called Subject in the TDX environment) with 

• [Application] / [System and version number(s)]: 
• Incident Model:
• Unit Overview:
• Examples:
  • Incident Model: MyU
  • Unit Overview: OCR - Office of Conflict Resolution 
  • TDX Knowledge: Create a Knowledge Base Article
  • TDX Major Incident: Communicate with Colleagues and Users 
  • Canvas: Add an Assignment to Your Course Site
  • Windows 10: Update Your Operating System

If an article applies to multiple versions, include the latest two versions in the title.

• Example:
  • Drupal Enterprise 8, 9: Enable the Folwell Theme

Note: TDX automatically generates the title of an article based on the Subject field. It serves as the summary heading for the article and is automatically formatted as a heading 1 (H1). For accessibility, a web page should only have one H1. Therefore, do NOT repeat the title in the TDX body field.

Additional Considerations for Website Content

Do not use acronyms in page titles, headings, or subheadings. Exception: Acronyms that are never spelled out, such as IT, can be used in those instances.

The first paragraph of every piece of content should be a brief description that provides context for what follows. It can be a single sentence. You can address the audience directly and tell them why they should read on.

The following is a before and after example of a description edited to provide additional context for a public audience:

• Before: This article provides instructions for installing the driver for the University of Minnesota WiFi printing on your device with a Windows operating system.
• After: You can send print jobs via WiFi to printers in UMN Public Computer Labs, but first, you need to install the necessary driver. The following instructions are for Windows.

Note: Don't create a heading for the article description (such as "Description" or "Summary"). The content title/subject will serve as the heading.

Additional Considerations for Comms

For MyU submissions and Brief entries, summary paragraphs are not required since these channels have word limits and other formatting requirements. 

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

Although we rarely write about the University itself, use the University of Minnesota System Identity Guide for boilerplate language (p. 4) and specifics on how to refer to the University (pp. 5-6). There are some important style guidelines to note:

• Upon first reference, always spell out the full name of the institution. For example, University of Minnesota Morris or University of Minnesota Twin Cities and then use the shorthand/acronym.
• For digital communications, UMN is the preferred shorthand (so you'd use UMN Twin Cities).

• Always capitalize University when referring to the University of Minnesota
  • The University-wide recommendations for device security are …
  • OIT provides technology support to the University community.
• Do not capitalize "system" when not coupled with "University of Minnesota" or "U of M."
• Use systemwide rather than system-wide

Additional University-specific style recommendations:

• University Relations Resources
• UMN Editorial Suggestions and Styles

Additional Considerations for Comms

None

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

The active voice describes a sentence where the subject performs the action stated by the verb. It follows a clear subject + verb + object construct that's easy to read. In fact, sentences constructed in the active voice add impact to your writing.

With passive voice, the subject is acted upon by the verb. It makes for a murky, roundabout sentence; you can be more straightforward with active voice.

In other words, for clarity and impact, put the doer in the driver's seat.

Example

• Passive voice: Canvas re-enrollment is possible for PeopleSoft entered TAs. 
• Active voice: You can re-enroll TAs if they have been entered into PeopleSoft.

Example

• Passive voice: The disaster recovery orientation video can be watched by anyone using VPN.
• Active voice: Anyone using VPN can watch the disaster recovery orientation video.

Additional Considerations for Comms

None

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

Additional Resources

• Grammarly: Active vs. Passive Voice: What's the Difference? 
• YourDictionary: Examples of Active and Passive Voice

Begin each step with an active verb for step-by-step instructions. For example:

• Install
• Add
• Setup
• Find
• Go to

Example

• Select ON to activate the dashboard. 
• Go to the File menu. 

Additional Considerations for Comms

None

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

When you are addressing the audience, use you to refer to the user. (You do not have to use the pronoun when the subject of the sentence is already understood to be the user.) 

Examples

• Before you compress your video, you will need to balance the sound levels.
• Download the file to your computer.

Additional Considerations for Comms

None

Additional Considerations for Knowledge

Public articles

• Use "you" to refer to the audience.

Internal articles

• Use "you" to refer to the consultant and "user" to refer to the customer.
• Example:
  • Before you direct the user to open the zip file, you will need to…

Additional Considerations for Website Content

None

This article covers when to use a comma in communications.

After a sentence's introductory phrase

Use a comma after a sentence's introductory phrase.

Examples:

• When your computer makes a soft whirring noise, begin to open programs and applications.
• Because computers also can get tired, your computer may need a good cup of coffee to really start working well.
• In the beginning, listen to your computer and attend to what it seems to be asking for. 

Do not use to separate info at the end of a sentence

Do not use commas to separate the same chunks of information when they appear at the end of a sentence.

Examples:

• Begin to open programs and applications when your computer makes a soft whirring noise.
• Your computer may need a good cup of coffee to really start working well because computers also can get tired.
• Listen to your computer and attend to what it seems to be asking for in the beginning.

Coordinating conjunctions

Use commas with a coordinating conjunction (FANBOYS) to combine two complete sentences on either side of the FANBOYS.

FANBOYS = for, and, nor, but, or, yet, so

Examples:

• The computer didn't want to start up this morning, but it did begin to work well after lunch.
• The computer needed to be updated, for it had only been updated once in five years.
• The computer also needed to be plugged in so that it could function.
  • "That it could function" is not a complete sentence. Therefore, no comma is used before so.

Oxford comma (Series comma)

Use the Oxford comma to separate items of three or more in a list.

• The computer came with a mouse, monitor, and a power supply.
• To operate the computer, I had to plug in the mouse, hook up the monitor, and connect it to the power supply.

Parenthetical parts of a sentence

Use commas to separate parenthetical parts of a sentence. This comma guideline is often where extra commas sneak into the writing because the author thinks a pause is needed. Remember that the punctuation mark is needed for clarity and understanding more than anything else. Technical writing style doesn't often call for some of the more subjective times when you have to decide on the use of a comma or not.

• There are certain parenthetical parts that are more clearly defined, including dates, times, and city/state combinations:
  • Begin by driving to Oskalousa, Iowa, to find the best computer repair shop.
  • The computer repair shop is open on Monday, September 15, from 8 a.m. until 9 p.m., for the general public.
• There are also certain parenthetical parts that are clearly interrupting the sentence and are non-essential to the meaning of the sentence or helped by commas to add emphasis.
  • The computer repair person, who sometimes comes to work dressed up like a video game character, will take excellent care of your computer.
  • Your computer, thankfully, will get back to you in tiptop shape within 24 hours.

Use headings to identify the topics and subtopics of your content. Headings have several functions:

• Provide a quick overview of a section
• Act as visual dividers and make the content appear less dense
• Help mark the way and allow users to decide whether to read the content or not  
• Help you organize your content

If your content is long and/or there are numerous step-by-step instructions or items, consider breaking the content into topics. Users find multiple paragraphs or long lists more difficult to scan and follow. 

Additional Considerations for Comms

None

Additional Considerations for Knowledge

TDX Knowledge Use Headings for Proper Article Structure

Public article standard: 

• Headings for step-by-step instructions should use gerunds ("ing" verbs). Gerunds describe a process. For example: Creating, Adding, Moving.
  • Example: 
    • Adding Resources to the Dashboard
      You can add resources to the Dashboard using the Administration tab. 
      1. Select the Administration tab (bottom-right corner)
      2. Click Add a resource
      3. Choose the resource type, etc…
• As with subjects, avoid using How to in topic and subtopic headings.
• Our standard: No colon at the end of headings 

Additional Considerations for Website Content

None

Use lists to identify steps and lists of items. For lists with additional secondary information use sub-lists. 

Using Lists

• Use a bulleted (unordered) list if you have a list of more than two items in a row and order doesn't matter.
• Use a numbered (ordered) list if you have more than one step in step-by-step instructions. For steps use numbers (1, 2, 3...) and for sub-steps use lower alpha (a, b, c…) then lower roman (i, ii, iii...). If there is only one sub-step, use a bullet.
• Use the built in list functions on a page when available. 
  • If a page allows HTML, use the <li> list type.  
  • If the page uses a WYSIWYG editor, use the list function.
• If possible, list no more than nine steps or items. People can most easily read lists with five to nine steps or items. 
• Some processes with more than nine steps can easily be chunked but not all. If you can't break a lengthy list of steps into sub-topic(s) or a lengthy series into defined sections, try to make sub-step groups. 
• Although screen readers can detect bulleted (unordered) lists, they do not usually distinguish levels of indentation. Try to structure your long lists into smaller lists separated by headings. Find more information and examples on Accessible U: Lists.
• Example
  • In the example below, step 8 serves as subheading for steps a, b, and c. Otherwise, there would be 12 steps in the process.
  • Creating a Calculated Item
    1. Click the Formulas button on the ribbon.
    2. Select Calculated Item.
    3. Name the formula.
    4. Press Tab to move to the formula.
    5. Select the appropriate Field (if necessary).
    6. Double-click the appropriate Item(s).
    7. Press the + key on the keyboard.
    8. Continue creating the formula.
       1. Double-click the next Item.
       2. Press the + key on the keyboard.
       3. Repeat steps a) and b) until all Items have been added to the formula.
    9. Click OK.

List Punctuation

• Punctuate bullets consistently. If one bullet ends with a period, end all bullets with a period. 
  • If all bullets are sentences, end each one with a period.
  • If all bullets are phrases or fragments, use no end punctuation.
• Bulleted lists should ideally be introduced by a complete sentence that ends in a colon. There should be no punctuation (no capitalization or ending punctuation) unless they are complete sentences.
  • Example:
    • This update applies to the following operating systems:
      • iOS
      • macOS
      • Android
      • Windows
• The order for sub-lists with ordered lists is: numbered (1,2,3…), lower alpha (a,b,c…), lower roman (i, ii, iii…).

Additional Considerations for Comms

None

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

Links in digital content can be used to provide additional information to the reader beyond what is on the current page.

The most important thing is to make clear what the user will get when they click the link. Links should:

• Provide some information when read out of context
• Explain what the link offers OR provide the title (or close to it) of the target page, so that all users—including anyone using a screen reader—can immediately tell where that link goes. 
• Example of screen reader navigating links.

Considerations when creating links:

• Links should be blue (often the default) and underlined. 
• For scannability and accessibility, be as specific as possible with link text.
  • Link keyphrases rather than individual words and consider making minor copy edits to enable this. For example, linking the phrase "types of internet accounts" is more effective than only linking the word "types." 
• Avoid linking to the same resource multiple times in one piece of content. 
• When linking an entire sentence, do not include the period in the link.
  • Learn more about link accessibility. 

Never Use Click here (or other non-descriptive link text)    

"Click here" has absolutely no informational value. It makes it impossible to scan a page to see what other content possibilities there are. It doesn't tell the user anything about where the link leads. It's not good enough to provide context prior to the link.  

More importantly, "click here" makes it nearly impossible for a person using adaptive technology to efficiently work with the page. Example of screen reader navigating links. The same is true for the following (not a comprehensive list):

• Here
• More
• Learn more

Additional Considerations for Comms

None

Additional Considerations for Knowledge

Jump-to and In-page Links

When you want to allow a user to jump to another location in the page, such as a later section, leave the Target window as is <not set>. However, add "(on this page)" after the link. This is an accessibility standard.

An exception to adding "(on this page)" after the link is in a Table of Contents.

Additional Considerations for Website Content

None

Additional Resources

• Accessible U: Links
• WebAim: Link Text

When referencing the terms, tools, buttons, headings, etc. on a page, use the exact wording that the item you are referencing uses.

Use the Exact Wording and Capitalization

Refer to application interface terms just as they appear in the interface. Doing so allows people using screen readers and/or people who think in concrete terms to continue undeterred. 

• When an interface element is identified with a screentip, refer to it using the screentip text.
• When an interface element is not identified, an accessibility issue, describe its function and location. You can also provide a screenshot. 

Bold the Application Interface Terms 

Format application references bold. Using bold allows users to more quickly follow your instructions.  

Additional Considerations for Comms

None

Additional Considerations for Knowledge

None

Additional Considerations for Website Content

None

This checklist is for Knowledge Editors to use when approving internal articles in TDX and when publishing public articles to the IT site.

Table of Contents

• Process and Procedures
• Style
  • Article Title
  • Content
  • Format
  • Links
  • Images/Video
• TDX Article Settings

Process and Procedures

• Article is unique (no duplicate content). See Search for Duplicate Knowledge
• Curated content is properly referenced and has effective context. See Use Curated Content
• Author has collaborated with knowledge owner and other stakeholders
   

Style

Article Title

Internal Standards

• Leads with the service or application name and version number(s) followed by a colon (when applicable)
• Summarizes article contents

Additional Public Standards

• Uses the active voice, e.g., create, assign, secure
• Is 10 words or less
• Uses title case
• Uses words customers might search on
   

Content

Internal Standards

• First paragraph is a problem statement or description that provides context
• Sentences are concise and easy to scan; paragraphs are short
• Sentences are grammatically correct and contain no typos
• Uses simple language and terms 
• Content is well ordered; topics and subtopics are in a logical sequence 
• Refer to customers as callers or users; Refer to technicians as you
• Information is technically accurate, up-to-date, and complete
• Acronyms and abbreviations are defined on first use

Additional Public Standards

• Audience is clearly defined and is addressed as you
• No jargon is used unless understood by intended audience
• Content contains words customers might search on
• Content is directed to the appropriate audience throughout the article
   

Format

Internal Standards

• Topic and subtopic titles are formatted as headings
• Use numbers for steps, bullets for lists
• Application interface terms are referenced just as they appear in the interface 
• Application interface terms are in bold
• Table(s) have a header row(s)
• HTML is clean (see Remove Extra HTML Formatting from an Article)

Additional Public Standards

• Content is well ordered; topics and subtopics are in a logical sequence
  • Topic and subtopic titles: 
    • Are formatted as headings and are not bold
    • Use "ing" verbs when describing a process within the article content
       

Links

Internal Standards

• Long articles have a table of contents (TOC) that use in-page anchor links
• Link text clearly references the target content (see Create a Link in an Article)
• Links to other pages open in a new window

Additional Public Standards

• Links to other KB articles use the TDX URL, not the it.umn.edu URL.
• Email addresses are spelled out
   

Images/Video

Internal Standards

• Images are uploaded to server (not pasted in or attached)
• Images include appropriate alt text (see Make Images Accessible)
• Images are beneath the step(s) they illustrate
• Images have a TDX-generated 1 pixel border (set in Insert/Modify Image window) to define edges when necessary (see Make Images Accessible)

Additional Public Standards

• Images are essential to understanding the content and associated with the step they define
• Images are cropped and sized appropriately
• Videos have transcripts or closed captioning
   

TDX Article Settings

Internal Articles

• Article is in the appropriate TDX Knowledge Category
• Owner is set to a Group and selected based on agreement between stakeholders
• Tags include any appropriate technologies or services.
• Next Review Date is set
• Notify Owner on Feedback is checked.
• Article Summary is one sentence describing the article purpose
• Should the viewing of this content be limited to the University community? is set to the appropriate setting.

Public-Facing Articles

• Article is in the appropriate TDX Knowledge Category
• Article Summary is the first sentence of the article
• Tags include any appropriate technologies
• Published to KB is checked
• Next Review Date is set
• Appropriate Group is set as Owner, based on agreement between stakeholders
• Notify Owner on Feedback is checked
• Knowledge Internal Notes have been added when appropriate
• Should the viewing of this content be limited to the University community? is set to the appropriate setting.