Organization

Confluence is organized the way the program is organized. The primary modules are listed in the menu at the top: Circulation, Items, Patrons, Tools, Researcher, and Support. Each module has a landing page that directs users to content for that module. Some landing pages have Image Maps, like Patrons, Tools, and Preferences. 

We use Brikit Theme Press to design the Support Center. Read through the Brikit documentation to learn how it works with Confluence. You will refer to it often.

Spaces

Content is divided by space, and each space has a theme (style) and menu. 

I use the Testing space to test new layouts, theme changes, or anything else I don't want to be public quite yet. The Testing theme is one I was playing with to match the header and footer with the redesign and make the background less of a strain on my eyes. 

Page Titles

Pages are named after the module or section they belong to. 

No two pages can have the same title. This usually isn't a problem, but it can be. For example: 

• Circulation > The module landing page
• Circulation > The first tab in the Circulation module. 
• Circulation > Preferences

Preferences is a particular problem. Because nearly every preference is named after a module, each page includes "Preferences" in the title. 

• Circulation Preferences
• Patron Preferences
• Security Preferences

Duplicate Pages

One page cannot be included in two page trees, but some of them should be. For example, as a customer, I would expect to see information about Patron Preferences in the Patrons section.

To keep some related content together, the original page was copied and a space was added to the title so that page could be include in the other page tree. The copied page uses the Include Content macro to pull content from the original page, so there's still only one place to edit the content. 

For example: 

Most of the time, this kind of duplication isn't necessary. I don't love this solution, but I felt it was important to make certain content more accessible. 

Page Layouts

Alexandria is a complicated program, and some of the content is nested deep in the page tree. When you open a page, the Table of Contents on the left will highlight the page you're on and where it is in the page tree; however, it doesn't expand the tree to show content nested under that page, which means content can easily be missed. 

To solve this problem, we use Page Layouts. Each module has a specific Page Layout that contains a Table of Contents and title header specific to that module or section. For example, the Reports page shows all of the Reports subpages on the left, instead of the entire page tree. Breadcrumbs at the top of the Contents section will show you where you are in relation to the rest of the Support Center.

KeepnTrack and Textbook Tracker have only one Page Layout that shows the same Table of Contents for the whole program. This isn't as big of a deal because these apps are a lot smaller than Alexandria and content is less likely to be lost or missed.

Make sure to set the appropriate Page Layout after creating a new page. 

1. Type . (period) to open the designer. 
2. In the Page tab, click Page Design. 
3. If it's set to Use Space Default, click Override Design.
4. Select the correct layout for the content. 

You can view each Page Layout in the Theme Press Architect pages. Any changes you make there will affect all of the pages using that layout, so be careful.

Problems

Confluence is not perfect! You'll find there are a lot of inconsistencies and weird things going on in each Support Center. 

The search box is missing

Brikit has a setting to add the search box to the Brikit header, but confluence made some changes and now it doesn't work. It should be fixed in Brikit Theme Press 2.4. 

• https://support.brikit.com/browse/PRESS-2444 
• https://support.brikit.com/browse/PRESS-2446

Mobile view

It doesn't work well. You can view it on a mobile device, but any page with columns will be pretty messed up.

PDF / Printing view

It doesn't work well. You CAN DO IT but any page with columns will be squashed.

Circulation Tabs

This section is messy. In the app, some of the Circulation tabs have subtabs. Confluence doesn't do subtabs . . . To get around that, for each tab I set up a page with tabs for the subabs. Yep, it's confusing. The Circulation Tabs page is set up like the app, with the appropriate tabs, and content is "included" from the primary subpage. But tabbed content is listed on top of the other, which means the page is long and hard to read. Feel free to find a better way. Please. Please find a better way. 

• Circulation Tabs
  
  • Circulation tab: Transaction Log, Renewals, Homeroom
  • Holds tab: Patron, Item
  • Charges tab: Charges, History

Feel free to find a better way. Please find a better way. 

Other to-dos

• Landing pages : try to fix - search bar - text color + highlight color ... can't figure out how to edit (might need custom code)
• -also random 2 underscores at the 'header' of the support pages
• Note There is custom code for search functions (from Brikit) - like the space-specific function -
• Reports - 
• RUIE documentation issues draft for the project with Stephanie
• patron barcode labels 3x10 draft for start of report pages
• Later someone to-do:
• alexandria library space - clean up and add labels
• look at the advance tables macro for new possibilities
• courses, quizzes -- add-ons trials... remove or buy them

Editor Pages (Hidden) 

On the bottom left, go to Space Tools > Reorder pages. This is where you can see and reorganize pages in the various page trees. All customer documentation is listed under the Support tree.

At the top, click Editor Pages (Hidden). This is where I keep all of my drafts, notes, and content that customers don't need to see. The primary page and, subsequently, its child pages are locked so confluence-administrators and confluence-users who are logged in can view and edit the content. 

Ignore the How To pages. I was planning on using the instructions as excerpts, but I don't think we ever got around to it. These are likely old and just need to be deleted, but I didn't have time to check for sure. 

Archived Versions are old versions of articles for historical purposes. When I have to completely rewrite a page, I'll often copy the original page (Toolbar ... menu > Copy) and move it to my drafts. When it's done, I move the original to this archive, and move the new one to the right spot in the page tree. If you choose to do the same, make sure you rename the articles correctly, so the new one has the same title as the old one, and the old one indicates it's old or archived. 

Links

Bookmark these:

Library Spaces

All images, videos, excerpts, and other content are stored in the inclusion library and then reused in various places in the Support Center. 

Each brand has an inclusion library, and each library has most of the same pages.

Naming Schemes

Images are named to keep them organized by type and location so you can actually search for and find a specific image when inserting one into a Confluence page. And when the app UI is updated and you need to update an image, instead of going to each page the image might be on, just get a new screenshot, give it the same title and extension of the old one, and upload that to the library. The image will be updated everywhere it's included. 

The icnlud

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. 

For example: Alex S Tools Preferences Extras Clever

For example:

• Alex S Tools Preferences Extras Clever

Icons & Graphics

Name format: Alex G Module Specifics

PDFs

Name format: (for reports, this is usually the output name of the pdf)

Example Reports (PDFs)

Images

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

Name format: Alex S Module Location Specifics

• All library page titles should start with Alex.

Videos

The Videos library page has all of the library videos organized into sections.

• All multi-excerpts should be centered.
• All multi-excerpt titles should include the video ID (if applicable—we don't use these much anymore) and title.
• All multi-excerpts should be formatted with the title in H3 and the info icon next to it with a hover tooltip that includes the last updated date and the version it applies to – no punctuation.

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. 

Documentation

• Confluence Macros
• Brikit Macros

Specific Macros

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

• Page Titles & Headings: 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.

Terminology

See the Alexandria Library space Glossary. Note ones tagged with "companion" are company-wide terminology standards.

Page Structure

Heading 1

Heading 2

Heading 5

Heading 4

Screenshot Guidelines

• Dimensions: 1024 x 768 >> Makeover is 1366 x 768
  • Capture screenshots and present them on the page at their full-size.
  • Full-screen images should be resized to medium, about 533px. 
    
  • Avoid altering their size in an image editor—let Confluence do the shrinking (if required), because the user can always click the image to view its full size.

• Format: Save screenshots in PNG format.

• Usage: Only use screenshots when you really need them as a "location anchor" for users, but not for every point in a series of steps. One main image is often sufficient to describe the functions of a specific page, but additional images should be included when necessary.
  

• Only include necessary detail. When taking screenshots, omit any unnecessary detail. Only include the area of the page (or menu items) applicable to the context described in your documentation.

• Centered or indented: Screenshots should be centered, not indented (i.e. appear flush against the left of a page), unless they are part of procedural steps, in which case, use Confluence's Ctrl+Enter feature to ensure they are indented to the correct step level.

• Annotations: Use Preview or Snagit or annotations.

Stock Images

• Download: From our account on https://www.istockphoto.com/.
• Store: Sync > Support Center > iStock pics folder.
• Adjust 1: Run the image through Squash to compress the image. This saves space. Save it to the save folder, so you'll have an additional image with -squashed appended to the name.
• Adjust 2: Open the squashed image in Preview and choose View > Adjust Size, and make it smaller (say, 1200px wide, which is plenty). This saves a lot MORE space.

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.

Links

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

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.

Tabs

Brikit lets us have tabs on our pages. You can link to a specific tab by adding # plus the name of the article-Tabname, with no spaces.

e.g. http://support.companioncorp.com/display/ALEX/End-of-Year+Procedures
becomes http://support.companioncorp.com/display/ALEX/End-of-Year+Procedures#End-of-YearProcedures-Backups

Callout Boxes

Reading

Desktop Apps

How To - Macros