Confluence Style Guide

Created by Minjie Chen, modified by Kim Leaman on April 14, 2022

If you are asked to maintain or create pages in Confluence, here is the preferred style guide to follow.

Ease of Maintenance and Accessibility Requirements

Long-Term Maintenance Needs

First, recognize that your confluence pages Confluence may be maintained by many staff over time, who may or may not have experience working in Confluence. Please keep each page as simple as possible, and avoid the use of more complex features such as sections and expand boxes.

Excerpt boxes are an exception because they reduce duplication of content. For more on using Excerpts, see the Confluence documentation.

Similarly, you're encouraged to use Table of Contents and Children Display/Page Tree macros to improve internal navigation.

Web Accessibility Guidelines

See Princeton University guidelines on digital accessibility

Page Layout

Do not use Horizontal Rules (lines) across the page. User research has shown that people will stop reading at that point and not necessarily scroll down to further information. This is especially important "at the fold" - where the first block of text hits the bottom of their screen.

Section Heading Conventions

Page Title = Heading 1 (by default) - this is the overall topic for the page, use Title Case

Heading 2 = major sub-topics

Heading 3 = focus areas within sub-topics

Heading 4 = details within focus areas

Do not bold or italicize text within Headings - let the semantic style do the work.

Text Formatting and Style

Be careful when pasting text in from Microsoft Word - there is usually invisible formatting that comes along for the ride and interacts badly with Confluence formatting code. Best practice is to type your text in plain text in Word, then copy into the Confluence and format it there. This includes bulleted and numbered lists.

Use only bold or italics for emphasis. Do not use underlining - web users are conditioned to see underlining as indicating a hyperlink. See additional notes on using bold and italics in the Conventions to Refer to Alma Features section below.

One space after a period or other end punctuation. This convention makes online text easier to read. Two spaces after a period is an artifact of print publishing.

Avoid multi-sentence instructions whenever possible by breaking them into numbers/bullet points.

Conventions to Refer to Library Application Features

Use a caret to indicate going through a menu, and bold the entire sequence: Acquisitions > Invoices > Review

When referencing options in our applications:

Use bold (and only bold) to identify menu choices, buttons, or field names (e.g., Process type)
If you reference the same option or button multiple times in proximity to each other, only bold the first instance (or the emphasis will be lost)
Use italics (and only italics) to identify what you should type into a field, choose as an option, or see as a status (e.g., Item not in place)
Use the same capitalization as the button/menu item/field name/status does in the application, except where it would cause confusion.
Do not use underline and avoid quotation marks. Again, web users are conditioned to see underlining as indicating a hyperlink, and quotation marks add unnecessary clutter.
- Exception: When you say that a user should be working "at" a library location for Alma to function properly, use quotes. This acknowledges that staff may not be physically at the location they're working "at."

Resources

PlainLanguage.gov

Letting Go of the Words: Writing Web Content That Works by Janice (Ginny) Redish

Don't Make Me Think!: A Common Sense Approach to Web Usability by Steve Krug.

Title Capitalization Tool