Text Formatting

• Left-align text, never center or right-aligned.
• Leave one space between sentences. Never two. Or three. And four is just out of the question. Don’t even.
• Don’t use underline formatting, and don’t use any combination of italic, bold, caps, and underline.

Bold

Use bold when referencing in-app element, button and navigation labels customers will click on or interact with:

Example:

1. Click the Accounts menu at the top of the page.
2. Click Passwords in the submenu.
3. Scroll down to Two-Factor Authentication, and then click the Enable Two-Factor Authentication link.

To add a repository:

1. Go to Admin >  Repository List > Add repository.
2. Select a Repository type from the dropdown menu.
3. Specific fields will appear on the Add Repository screen, depending on the chosen repository type. Enter the repository details as prompted. You will find more information in the specific sections listed below.

Capitalization

• Capitalize the first letter of the first and last words. Capitalize the first letter of all words in between, with the exception of articles (a, an, and the); coordinating conjunctions (and, but, for, nor, or, so, and yet); and prepositions of four letters or fewer (at, for, with, into, etc.).

• Use proper capitalization for proper nouns, including the names of COMPanion products, features, pages, tools, and team names, when referred to directly. In step-by-step instructions, capitalize navigation, field, and button labels as they appear in the app.
  • COMPanion, Alexandria, Textbook Tracker, KeepnTrack
  • Circulation, Circulation Management
  • Tools
    
    • Go to Tools and select Preferences. 
    • Export is a tool to...

• Do not capitalize common nouns that simply describe the product or feature, even when it's also the proper name of a module. 
  • In the Title Information report, you can choose to include records with a specific policy, like Fiction or Non-Fiction.

• Do not capitalize for emphasis.

• Do not capitalize random words in the middle of sentences. Here are some words that we never capitalize in a sentence:

  • website
  • internet
  • online
  • email

Hyphens

• Use hyphens to create compound words.

• Be consistent with which words you hyphenate.

• A prefix carries a hyphen if the second element is a capitalized word or numeral (un-American, pre-1914).

• Hyphenate if the compound is a homonym (re-create means to create again, recreate means to take recreation).

• Use an en dash (–) instead of a hyphen to indicate ranges, such as 1991–2010.
  
  

Italics

• Use italics for emphasis, but don't overdo it.

• Use italics for specific references to the titles of guides, reports, imports, exports, utilities.

• Avoid using italics in on-screen text; it's hard to read.

Punctuation

Ampersands

• Try to avoid using them, but they’re okay if space is a major concern.

Apostrophes

• Its is possessive. Each template has its own title.
• It’s is a contraction for it is. It’s going to launch on Friday.
• Never use an apostrophe on plural acronyms. Most ISPs use spam checkers.

Commas

• Love that Oxford Comma! Put a comma before the last item in a series: Email, surveys, and events. Otherwise, use common sense. If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma. (See what I did there?)

Ellipses

• The most common use for ellipses in UI copy is to add a sense of suspense.  Use them sparingly. Don’t use them for emphasis or drama, and don’t use them in titles or headers.

Exclamation points

• These show you’re really psyched about something, so only use them if you’re bouncing off the walls with excitement. Which you shouldn’t be all the time.

• Never use more than one at a time. They’re like high-fives: A well-timed one is great, but too many can be annoying.

• Never use exclamation points in failure messages or alerts.

Parenthesis

• In standard sentences, avoid enclosing text in parentheses. It breaks up the sentence and can be hard to follow. Instead, try to rephrase the sentence or use commas for closely related material and dashes for less related material.

• Use sparingly to refer to something as a side note. When addressing a phrase that could be singular or plural, always go for generic plural.
  • Say:  Select the contacts to remove.
  • Instead of:  Select the contact(s) to remove.

• Enclose an expression, such as that is or namely, and the element it introduces in parentheses only if a comma doesn't signal a big enough break in continuity:
  • The task has been closed, that is, the Status field has a “Closed” value.
  • Users in a territory can be granted read, read/write, or owner-like access (that is, the ability to view, edit, transfer, and delete records) to the accounts in that territory.

• Don't use parentheses within parentheses. Instead, rephrase; if necessary, change the second set to brackets.

• Place semicolons and colons outside quotation marks and parentheses.

• Place question marks or exclamation marks inside quotation marks, parentheses, or brackets only when they’re part of the quoted or parenthetical matter.

• When parentheses or brackets enclose an independent sentence, place the period or comma inside. Otherwise, place the period or comma outside.

Periods

• Be consistent. Use a period at the end of each list item, or don’t. Just don’t do both.

• Using quotation marks? Put the period inside the closing mark. Example: Damon said, “I ate all the donuts.”

• Periods go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
  • Outside: I ate a donut (and I ate a bagel, too).
  • Inside: I ate a donut and a bagel. (The donut satisfied my sweet tooth.)

• When abbreviating the time of day (which is always), use am and pm, lowercase without periods. And be sure to add a space after the digits.
  • Example: 8:30 am – 9 pm

Quotation marks

• Only use for actual quotes, never for emphasis.

Theme

Headings

Structure • Links • Lists • Instructions • Tables • Examples • Callout Boxes

The Anatomy of a Page

IMAGE

• Page Layout. 

Links

Include a concise, contextual link whenever you’re referring to another page in Confluence or something on an external website. Do not link terminal punctuation. Prefer shorter links to long ones. Don’t include preceding articles (a, an, the, our) when you link text.

• No: Refer to our install guides for details.
• Yes: Refer to the Alexandria User Guide for details.
  
  
• No: Check out our Administration Settings article for more information.
• Yes: Check out 7.17.7 Release Notes for more information.

Cite knowledge base articles as follows:

• No: Read this article for information on attachments.
• No: For more information see Avatar attachments.
• Yes: For more information, see Avatar attachments.

Don’t say things like “Click here!” or “Click for more information” or “Read this.” Write the sentence as you normally would, and link relevant keywords.

Lists

• Only use numbered lists for step-by-step instructions. Separate steps into logical chunks, with no more than two related actions per step. When additional explanation or a screenshot is necessary, use a line break inside the list item.

• Use bullet-point lists to indicate a range of choices or non-sequential items.

• Lists should never go more than three layers deep.

• If any item in a list (ordered or not) forms a complete sentence, all items must begin with a capital letter and end with a terminal punctuation mark.
• If no items in an unordered list form a complete sentence, skip the capitalization and terminal punctuation.
• If the items in the list complete an unfinished introductory sentence, end all but the last item with a semicolon, add an “and” before the final item, and finish off with terminal punctuation.
  
  

Tables

Use tables sparingly. Tables used for formatting are difficult for screen readers and other accessibility devices to interpret properly. Think about whether a list would be sufficient - or simply use carriage returns. For more information on tables and accessibility, see: Web Content Accessibility Guidelines 1.0: Guideline 5 Create tables that transform gracefully.

Note that the {section} and {column} macros will insert tables into your page when they render your content, so the same caution applies to using these macros to create a multi-column page or section.

Structure

Pages are formatted as such:

Lists

Links

1. Cross Referencing
1. Visit the Microsoft Accessibility Website to learn more.
2. Link imperative sentences
   
   

Steps & Instructions

1. Choosing Bullets or Numbers
2. Maintain Parallel Construction
3. Punctuating and Capitalizing Items
   
   

Tables

Examples and Quotes

Callout Boxes

Naming Scheme

Page Titles

When naming pages, do not choose names that will be obscure. Stick to standard names and names given by software companies, developers, etc. If the subject/idea has a proper name then you should try and make that the page name. For instance, “Adobe Acrobat Professional 9” is often referred to as simply "Acrobat Pro” or “Acrobat" but you should make the page name “Adobe Acrobat Professional 9” because this is the actual name. Sometimes it's not clear what the real name of the place/thing/idea you're making a page for should be. In these cases of confusion, just make a decision as to what the page name should be, then make note of the alternative possibilities in the page itself. Referring to the other possible names allows people to do searches and find the page under any of the possible names. An example of this is “PaperCut”, which is also “BearPrint”. It's not clear what the name of the page should be, so a simple reference to the other name (somewhere in the page, probably toward the beginning) fixes this and allows people to find it in a search. Also utilizing the proper Label will categorize the page and aid in searching. Searching is very important, especially for people who don't use the site regularly.

• Different types of articles should follow different naming conventions.
• All How-to article titles should begin with How to.
• All Troubleshooting article titles should being with Troubleshooting.
• Reference articles should NOT typically include "reference article" in the title. Instead, follow the general page name suggestions discussed above.
  
  

Images

Videos

PDF Documents

Installation Guides

• IGA = Installation Guide Alexandria product only
• IGK = Installation Guide KNT product only
• IGS = Installation Guide Scanner
• IGC = Installation Guide Camera

Numbers:

• Guides are numbered 001- 999 these are random values to separate each individual guide in each product line (Alex, KNT, Scanner, Camera).
• Numbers appearing after the decimal is the revision number of the guide (i.e. 0.0 = original, 0.1 = first revision, 0.2 = second revision, etc.)

Tabbed Pages

Notes

• The title of the block/tab must match the name of the H2 header on the tab page in order to show up in the Contents list in the title header.
• When using the "Include Content" macro, Back to Top links only work on the actual tabbed page – they will not work if they are "included" on the page from the original content.
• Use H4 for tabbed page anchor links.
• Because we don't want all H2 headings to be included in the Table of Contents, all "included" pages must use H1 headings. The tab titles should show the topic well enough for navigation, then we'll include H4 anchor links for subcontent on each tab.

RELEASE NOTES

• Each item under New & Improved should begin with a verb.
  
  • New
  • Updated
  • Improved
  • Fixed
  • Enhanced
  • Corrected

The Alexandria Library space is where all images, videos, excerpts, and other content are stored. The content is then reused in various places in 

We have an inclusion library for each brand, and each library has most of the same pages. When inserting an image into a page, select the 

Insert Images

1. Command + M, or go to + and choose Files and Images.
2. Search on other pages
3. Enter your search term(s). 
   
   1. For best results, enter search terms that match the file name format. First enter the brand (Alex, TT, KNT), type (S for screenshot, G for graphics), module, and location. For example, Alex S Items will return all Alexandria screenshots from the Items module. The more specific you are, the fewer your results, and the easier it will be to find that specific image.
   2. If searching multiple terms, they must be in the same order as the file name. For example, searching for Notes Items will return different results than Items Notes. 
   3. If you're looking for 
   4. I 
4. Scan the results to find the image you're looking for. 
   
   1. The search results include an image thumbnail, the image title, and the page on which the image is located. 

Naming Schemes

Images are named to keep them organized by type and location in this format: Brand Type Module Location Secondary_Location.

• Use a space between each term and an underscore between a term with two or more terms. 
• Hyphens are only used if the term itself is hyphenated, such as Self-Service. 

Alex S Module Location Secondary_Location

Brand: 

• Alex
• TT
• KNT

Type

• S: Screenshot
• G: Graphics
• KB: Knowledge Base - An image that was created for the knowledge base
• KBM: Knowledge Base Marketing - An image created by Marketing, such as an infographic or graphic used on our website. 

Module or 

• Alex G Tools Preferences Extras Clever 

• S: Screenshot
• G: Graphics
• KB: Knowledge Base - An image that was created for the knowledge base
• KBM: Knowledge Base Marketing - An image created by Marketing, such as an infographic or graphic used on our website. 

Content

Icons & Graphics

Name format: Alex G Module Specifics

Images

This is primarily screenshots of the Alexandria program, though some images may be for other things

Name format: Alex S Module Location Specifics

Videos

The main Videos library page has all of the library videos organized into tabs. This page is included on 

Reading

Desktop Apps

How To - Macros