Confluence Style Guide
- Minjie Chen
- Sal Hamerman
If you are asked to maintain or create pages in the Alma Confluence, here is the style guide to follow.
Ease of Maintenance and Accessibility Requirements
Long-Term Maintenance Needs
First, recognize that the Alma Confluence will 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.
Alma Terms - Spelling and Conventions
Alma Spelling and Capitalization
Alma Production and Alma Sandbox: Capitalized when used as proper nouns, lowercase when used more generically.
Metadata Editor is capitalized in that way, as a proper noun.
One-Time Order
Conventions to Refer to Alma Features
Use a caret to indicate going through a menu, and bold the entire sequence: Acquisitions > Invoices > Review
When referencing options in Alma:
- 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 Alma, 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
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.