Alma Wiki Style Guide

If you are asked to maintain or create pages in the Alma wiki, here is the style guide to follow, developed in May 2019 by Jennifer Koerber, Alma Training Manager.

Ease of Maintenance and Accessibility Requirements

Long-Term Maintenance Needs

First, recognize that the Alma wiki 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, 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.

Don't Refer to Aleph

During the first year of Alma, it was important to make connections between what staff were used to in Aleph and what they were learning in Alma. After a year of working in Alma, it's now important to stop referring back to Aleph and focus on Alma on its own terms.

As of June 2019, do not refer to Aleph to describe how Alma works here in the documentation wiki. This will not be useful to newer staff or staff who've never used Aleph, and it focuses on the past instead of future.

As pages are revised and updated, continue to remove references to Aleph until the wiki entirely focuses on Alma.

Harvard Accessibility Requirements

If you aren't already aware of Harvard's Accessibility Requirements for online materials, please take the time to review them. This policy affects public-facing pages (and the Alma wiki is nearly entirely public) created or edited after 12/1/2019, as most pages in the wiki will be.

This isn't just for the public: library staff who need Alma documentation may use a number of adaptive tools - including closed captions, screenreaders, dictation-directed navigators, and screen magnifiers - and we are responsible for making our wiki as accessible as possible.

The Online Accessibility resources from HUIT offer direction and support for accessibility efforts. Begin with The 10 Essentials and go from there.

A shortlist of required accessibility features or best practices for every wiki page:

All videos must include a transcript of the audio or a copy of the script used to make the video (at minimum), closed captions (preferred), or both (best).
All screenshots must include Alt Text. Click on the image, choose Properties, then Title, and add a description of the image to the Alt Text box.
You may not use a screenshot as the only means of conveying information. You must include in the page text all of the important information from the screenshot. The screenshot should be there to support the text, not the other way around.
You may not use a table to format a page. This is both bad practice and makes use of a screenreader difficult.
Consistently use hierarchical structure for sections (see below for Alma wiki best practices) and use the appropriate semantic markup (the Heading 1, Heading 2, etc. styles available in the formatting bar) for each level.
Avoid large blocks of text, use bulleted and numbered lists to break up lists of information, and use Plain Language whenever possible.
Do not use red or green text as the only identifier of important text (to avoid red/green colorblindness issues). You must also use bold format or identifying language to note important details.

Online Accessibility Resources

Overall Style

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, use Title Case

Heading 3 = focus areas within sub-topics, use Title Case

Heading 4 = details within focus areas, use Title Case or Sentence case as appropriate

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 wiki 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 a artifact of print publishing.

Do not use periods at the end of instructions unless the line is a multi-sentence instruction. Related: avoid multi-sentence instructions whenever possible by breaking it into two 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 double 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 or 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."

Suggested Resources

These are resources used widely within the web design and user experience fields:

PlainLanguage.gov

w3c

Letting Go of the Words

Don't Make Me Think