Page Elements

General editing priciples and tips for all pages, including how to add a title, headings and subheadings, links, buttons, and lists.

Page titles

Titles organize pages and guide readers. A title appears at the beginning of a page or section and briefly describes the content that follows.

Titles are (you guessed it) in title case (every word capitalized except for a, an, and the).

Don’t use punctuation in a title unless the title is a question.

H1 is reserved for titles.

Headings and subheadings

Headings and subheadings organize content for readers.

Headings (H1) give people a taste of what they’re about to read. Use them for page titles only.

Subheadings (H2, H3, etc.) break articles into smaller, more specific sections. They give readers avenues into your content and make it more scannable.

Headings and subheadings should be organized in a hierarchy, with heading first, followed by subheadings in order. (An H2 will nestle under H1, an H3 under H2, and on down.)

Include the most relevant keywords in your headings and subheadings, and make sure you cover the main point of the content.

Be consistent with how you phrase titles. If your guide or tutorial has several pages, stick to the same naming convention for scannability, such as:

Nouns: Policies, Teams, Offices
Verbs: Create an account, File a report, Download our data

Use title case for page titles (h1). Use sentence case for subtitles H2 and smaller. In sentence case, you do not capitalize every word (you write it as a sentence).

Buttons

Buttons should always contain actions. The language should be clear and concise. Capitalize every word, including articles. It’s OK to use an ampersand in button copy.

Examples:

Lists and instructions

Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction.

Number lists when the order is important, like when you’re describing steps of a process.

Don’t use numbers when the list’s order doesn’t matter.

Use clear verbs to tell readers how to interact with interface elements:

Choose from drop-down menus.
Select or deselect checkboxes and radio buttons.
Click or tap buttons.
Follow or open links

Emphasize the interface label, e.g.

Enter your Library Card Number and PIN
Click Log In

Use the greater than symbol > for hierarchical menus:

In the Circulation menu, go to Reports > Annual Reports > Current Annual Report

Images and screenshots

Images must use alt text.

Images should not be the only method of communication, because images may not load or may not be seen. Avoid using images when the same information could be more clearly communicated in writing. See tips for when to include images.

Avoid the ‘zig-zag’ image layout. Format images all to the left or right on a page.
Avoid using images of fonts. If you need to use a screenshot, aim for high contrast between your font and background colors.

Add images using the image icon in the body text editor:

Alt text

Alt text is a way to label images, and it's especially important for people who can’t see the images on our site. It also improves search results.

Alt text should describe the image in a brief sentence or two.

When you upload an image you will be prompted to add alt text:

Format

Photographs should be in .jpg format.
Screenshots and graphics should be in .png format.

Screenshots

Take screenshots of what your user sees, and avoid screenshots of the entire screen - this can be overwhelming and hard to read.

Focus on the specific element you are demonstrating, with just enough context the user knows where the element is on the screen.

Video

Videos must include closed captions. YouTube provides instructions to edit and add closed captions.

Consider these additional best practices for video content.

Tables

Tables are only for tabular data: two or more “objects” (rows) that share two or more “values” (columns).

Add tables as a page section, or in the body text editor.

In tables, column widths are the same for all rows, which can make them easier to scan visually.

Tables are easily navigable for sightless users so long as the content is organized in a logical way. Here are some other guidelines to consider:

When listing numbers, it’s good practice to align them to the right of their cell, with the same decimal precision (“40.50” and “1.00”) so that the numbers are easier to compare while scanning.
Always align column headings up with the values in the columns. For example, numeric column headings should be aligned right if the values are, too.

View guidelines for accessible tables from WebAIM.

Files

Only use files for content that is meant to be offered in print, or downloaded and manipulated. For example, a patron brochure or a dataset in spreadsheet form.

Always include the file format in a link to a file.

Example: Download the meeting agenda (PDF)

For meetings or agendas, include the date created or the meeting date as YYYY-MM-DD first, followed by an underscore. For other documents, do not include a date.
Always separate words with an en dash (-). Don’t use spaces.

Examples:
- 2020-01-01-agenda.pdf
- 2010-01-01-minutes.pdf
- usability-testing-handbook.epub

Linking conventions

Include the document format in the link, at the end of the description in parentheses.

Examples:
- Download the Usability Testing Handbook (PDF)
- Download the Membership Map (PNG)

Formats

Offer documents most widely available format, while also including an editable source when necessary.

For example, include a brochure as a Word file and as a PDF.

Updating files

It is always preferred to update a file instead of uploading a new version. Then the same link will work, and display a new file.