UC San Diego SearchMenu

Common Revisions for Blink Content

Editing hand

Learn about the most common revisions made to new and updated pages in Blink.

When new content is added to Blink, either as a new page or edits to an existing page, Workplace Technology Services reviews the content. We check the content for:

  • Formatting: Such as headings, links and contact information
  • Key fields: Such as system names, intros and summaries
  • Following the UC San Diego Style Guide
  • Typos

These common revisions can be used as best practices guidelines for Blink and other UC San Diego web pages.

Avoid copy-paste from Word to the CMS

Many formatting issues arise from using copy-paste from a program like Microsoft Word into the Content Management System (CMS). We recommend that you prepare your content in a text editor, such as Notepad++ or Sublime Text, instead of a word processor. Word processors can add invisible formatting code to your text that interferes with the CMS. This often means that you will need to use the CMS to format and add links to your text.

Expand all

Links: No new windows

Links should open in the same window.

This is the default setting in the CMS, but if you copy and paste links from elsewhere, you may inadvertently be copying a link that opens in a new window. In the CMS, if you see a new window symbol after your link ( new window icon), then you need to go back and set the link to open in the same window. Choose Target: None in the Inset/ Edit Link box.

Rationale

Current best practices and ADA compliance advise against launching new windows for links. The default behavior is for users to use the back button when navigating a site. See the W3C Spec.

While some people may prefer links opening in a new window, it is easy for a user to choose to open a link in a new window. It is very difficult to do the opposite (make a link set to open in a new window instead open in the same window).

Links: Use descriptive link-text

The text used for a link should clearly indicate the link's destination.

Avoid:

  • 'Click here' and similar generic phrases as links
  • Full URLs as links

Examples

Rationale

Users shouldn't have to guess where a link will take them - it should be clear from the context and the link text.

When someone uses a screen reader, it is a common practice to skip from link to link in order to find information. Screen readers read the link text to the user. Hearing 'Imprints service agreement' is informative. Hearing 'click here' is not. When a full URL is encountered, some screen readers read the text very literally ('h t t p colon slash slash... etc.). While this may eventually be informative, it is frustrating.

Exceptions can be made when the URL itself is crucial information being conveyed.

Example from the UC San Diego Editorial Style Guide page:

Note: This page has a friendly link that's easy to remember: http://blink.ucsd.edu/go/styleguide

Links to login pages: Include 'login required' in parentheses

Identify links to login pages with 'login required' in parentheses (plain type) after the link.

Example: JDOnline (login required)

Rationale

Users shouldn't be surprised when they are prompted for login credentials. Remember that while Blink is intended for UC San Diego Faculty and Staff, it is aimed at newer employees and is accessible by the general public. While you may know that a certain system requires login credentials, do not assume that others do as well.

Some content contributors force links to login pages open in a new window. We recommend against this. Remember that users can choose to open a link in a new window. Giving users control of their browsing helps create a web page with a positive user experience.

Links to files: Include file type in parentheses

Include information about the file type in the link to a file.

Example: Academic Calendar (PDF)

Proper formatting

Put the name of the application or format in parentheses (plain type) at the end of the link:

  • Link text (Excel)
  • Link text (PDF)
  • Link text (PPT)
  • Link text (Word file)
    • Note: Use "file" after Word only.
  • If you have another file type, use a standard name or abbreviation for that file

Rationale

Users shouldn't be surprised when they click on a link and a new program opens on their device. This is especially true for users on mobile devices - opening a large file on a phone is much more inconvenient than on a desktop.

File and image upload locations

Do not put your files and/ or images in the same CMS folder as your web pages.

  • Files should go in a sub-folder of _files.
  • Images should go in a sub-folder of _images.

Be sure to use (and create, if needed) sub-folders to organize your files and images.

Rationale

Information should not be duplicated online or in the CMS. Duplicate information is more difficult to update because you can more easily forget about one of the duplicates. Once your pages have conflicting information, your users will be less likely to trust them.

To avoid duplicate information in the CMS, we have dedicated areas of files and images. This means there is only one place to check to see if you have the latest version of a file, for example. This also helps keep the CMS organized.

Many people use the Blink CMS, so it is important to keep it organized. Additionally, other people may need to find your files and images in the CMS, so we should be consistent with how we place them.

If you upload your images or files outside of the appropriate _images or _files folder, they will have to be moved. This can break links for your users. Prevent this by uploading them to the proper location the first time.

Proper use of the Intro field

The Intro field is required in Blink. Use the Intro field to tell users what they can do on this page. It can be used to help users know whether they are on the page that they need.

Do not put page content in the Intro field. Content should go in the Main Content > Body field.

For example, the intro to this page is: "Learn about the most common revisions made to new and updated pages in Blink." This tells the user what they can do (Learn about X) and helps disambiguate it from other pages (how to make edits, for example).

Often the intro text will simply explain the page title in more detail. This is fine. The intro should be brief and clear.

Rationale

Blink is a large site, and many pages and page titles can look similar. The Intro field is where we can help users figure out if they found the page they were looking for. The text in the intro is usually used in the Summary field as well, which appears in search results. This helps users figure out which search result they want to click on.

 

Proper use of headings

Do not skip heading levels. Some SMEs use headings (especially Heading 4) to bold text instead of using bold. Use bold to format. Use headings for organization. Treat headings like levels in an outline. Just like you wouldn't skip numbers in an outline, don't skip heading levels. (Note: there is no rule that you have to have use at least two headings at a given level, unlike how outlines are sometimes taught.)

  • H1: Page Title
    • H2: First major content section
      • H3: Subsection
      • H3: Subsection
    • H2: Second major content section
      • H3: Subsection
        • H4: Minor subsection
      • H3: Subsection

The title of a page is always Heading 1. Every page should have exactly 1 Heading 1 heading. In the Blink template, H1 is automatically generated from the 'Title' field. Do not add another Heading 1 to the page.

Drawer template: If you are using a drawer template, the 'Drawer Title' is always a Heading 2. Do not put another Heading 2 inside the drawer - this will cause the drawers to malfunction. If you use a header inside a drawer, start with Heading 3.

Rationale

Headers do not only influence formatting - headers are a factor used by search engines to determine search results. Skipping headers can confuse the search engine, leading to poor search results for your page. Skipping headings also disrupts the visual style of the site.

Resources

Break up large blocks of text

Writing for the web is not like writing for print. Using the same text from a large document on a web page often creates a sub-par user experience.

Break up your large blocks of text by:

  • Shortening your sentences
    • Using active voice
    • Using multiple simple sentences instead of longer, complex ones
    • Deleting repetitive statements
    • Deleting extraneous words/ phrases (especially at the beginning of sentences) such as:
      • "Please..." Users are already here to get information. They don't need to be asked politely to get it.
      • "Click on the link..." Users know what to do with a link. If you have provided the relevant context, no 'clicking' instructions are needed.
      • "In the following..." Focus on providing the information now rather than explaining how you are about to provide the information.
  • Using headings to organize your content
  • Using lists instead of long sentences when possible

Rationale

Web readers want information right now, so they:

  • Speed through text at a few seconds per page
  • Scan pages for quick information, focusing on left margin (usually the beginning of sentences)

Assist your readers by formatting your text for easy scanning.

Resources

Only one space between sentences

Use only one space, not two, between sentences in the same paragraph.

Rationale

The text as you see it on your screen is not necessarily the way users will see it. Users can set individual screen resolution and font sizes. This can cause a difference in how sentences wrap on the screen. This becomes an issue when a space is wrapped to the beginning of the next line, resulting in text that looks like this:

Double spaces interact with how sentences will wrap on the screen.
  This becomes an issue when a space is wrapped to the beginning
of the next line.

People scan web pages, rather than read them word for word, and pay more attention to the left side of the text. An inadvertent indentation can confuse a user and slow them down from finding what they need.

Additionally, these inadvertent indents make the page look like they were carelessly put together.

If you look at a paragraph on your page and feel that you need double spaces between sentences to make the paragraph look pleasant or read well, then your paragraph is probably too dense for the web. Shorten your sentences, break up the block of text and use headers or lists when appropriate.

Formatting: Use bold. Avoid underline, all caps and italics

If you need to highlight words, use bold, but use it sparingly. Lines of bold text don't stand out much more than lines of plain text. Choose only a few key words to bold.

If your page has an abundance of bold text, you should rewrite the content to be more clear.

Do not use underlining for formatting.

Avoid italics when possible.

Do not use all caps for emphasis.

Rationale

Underlining represents links on a web page. If you underline text that is not a link, you risk frustrating users.

Italics are difficult to read on smaller screens and create problems for readers with dyslexia.

All caps indicates yelling on the web. Do not yell at your readers.

Use of a.m. and p.m.

The UC San Diego Style Guide uses lowercase a.m. and p.m. with periods after each letter.

Do not use AM and PM.

Rationale

It is important to be consistent throughout Blink and UC San Diego web pages. With a few exceptions, we follow the Associated Press style.

Expand all