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.).
• 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.
• The following prefixes normally don't require a hyphen: ante, anti, bi, bio, co, counter, extra, infra, inter, intra, macro, mid, mini, multi, non, over, post (after), pre, pro, pseudo, re, semi, sub, super, supra, trans, ultra, un, under.
  • Exception: when a prefix stands alone, it carries a hyphen (over- and underused).
  • Other exceptions: the prefix carries a hyphen if the second element is a capitalized word or numeral (un-American, pre-1914) or the compound is a homonym (re-create means to create again, recreate means to take recreation).
• When the prefix ends with a vowel and the root begins with a vowel, such as pre-existing, hyphenate.
• When a measurement is used as an adjective, use a hyphen to connect the number to the measurement, as in 10-point type. Otherwise,
• don't use a hyphen.
• Hyphenate a fraction written as words: Three-fifths, Four and one half.
• Hyphenate a two-element number under 100: Sixty-three, twenty-one.
• 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.
• Avoid using italics in on-screen text, as italic text is hard to read.
• In documentation, use italics for specific references to the titles of manuals, books, magazines, disks, videotapes, films, audiotapes, catalogs, bulletins, and promotional literature.

Paragraphs

Be concise

• Don't add text if it's not needed.
• Use as few words as possible.
• Focus on users' tasks; write only what is necessary for users to complete them.
• Avoid unnecessary and redundant information.
• Keep tasks short.

Design text for easy scanning

• Users often scan, rather than read, text, so design the information for scanning.
• Place the most important points first and then add supplemental information if necessary.
• If you have multiple pieces of information to convey, use bulleted lists for easier scanning.
• Users read actionable text before explanatory text, so place actions first and then add explanations if necessary.
• Assume that once users have decided what to do, they immediately stop reading and do it.
• Use See Also links at the end of topics to refer users to related information. Avoid inline links whenever possible.

Avoid large blocks of text

• Keep only one topic per paragraph.
• Avoid long, complex sentences. Write so readers only have to read the sentence once.
• Keep your average sentence length less than 17 words.
• Make smooth transitions, using words and phrases such as also, in addition, moreover, consequently, however, although, for example, next, first, finally, and in contrast.
• In running text, generally avoid a string of one-sentence paragraphs.

Parallel Construction

• Use the same grammatical form for words or phrases in lists, titles, headings, or any other group of items that are related in grammatical structure or function.
• For titles, headlines, and headings, be consistent with equivalent headings throughout; that is, use nouns, noun and gerund phrases, or questions.
• Keep items in a series, list, or table parallel. Don't mix fragments and full sentences.
• Keep elements within a sentence parallel.

Parentheses

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.

• 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.

• Watch for misplaced parentheses, or an opening or closing parenthesis that lacks a partner.

• Use brackets to set off information already within parentheses.

• 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.

Punctuation

• Ampersands
  • Try to avoid using them, but they’re OK 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 (unless you’re hyped up on Club Mate).
  • 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
  • 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.
• Periods
  • Rule #1: Be consistent. Use a period at the end of each list item, or don’t. Just don’t do both.
  • Rule #2: Using quotation marks? Put the period inside the closing mark. Example: Damon said, “I ate all the donuts.”
  • Rule #3: 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.)
  • Rule #4: 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.
• Spacing
  • Use one space between sentences. Never two. Or three. And four is just out of the question. Don’t even.

Capitalization

• Capitalize the names of modules when directly referencing those modules.
  • Go to Items Management. 
  • In Tools...

• When using title case, capitalize the first, last, and all other major words. Lowercase “and,” “but,” “for,” “or,” and “nor” unless they are emphasized in a particular heading.

• Capitalize proper names of COMPanion products, features, pages, tools, and team names when directly mentioned. In step-by-step instructions, capitalize navigation, field, and button labels as they appear in the app.
  • MailChimp, Mandrill
  • Campaigns page, Lists page
  • Compliance Team, Billing Team
  • Navigate to the Automation page.
  • Click Save & Close.

• The words “internet,” “net,” “web,” and “website” should be capitalized as seen here (which is to say, not capitalized) when they’re found in sentence-cased text. E-mail and e-commerce take the hyphen, but not a capital “e.”

• Don't capitalize random words in the middle of sentences. Here are some words that we never capitalize in a sentence. For more, see the Word List.

  • website
  • internet
  • online
  • email
• • Title bar text
  • Toolbars and toolbar button labels
  • ToolTips
  • Web and Web-like page titles
  • Web and Web-like navigational elements (unless prohibited by the page design)
  
  

Hyphens

• Use hyphens to create compound words.
• Be consistent with which words you hyphenate.
• The following prefixes normally don't require a hyphen: ante, anti, bi, bio, co, counter, extra, infra, inter, intra, macro, mid, mini, multi, non, over, post (after), pre, pro, pseudo, re, semi, sub, super, supra, trans, ultra, un, under.
  • Exception: when a prefix stands alone, it carries a hyphen (over- and underused).
  • Other exceptions: the prefix carries a hyphen if the second element is a capitalized word or numeral (un-American, pre-1914) or the compound is a homonym (re-create means to create again, recreate means to take recreation).
• When the prefix ends with a vowel and the root begins with a vowel, such as pre-existing, hyphenate.
• When a measurement is used as an adjective, use a hyphen to connect the number to the measurement, as in 10-point type. Otherwise,
• don't use a hyphen.
• Hyphenate a fraction written as words: Three-fifths, Four and one half.
• Hyphenate a two-element number under 100: Sixty-three, twenty-one.
• 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.
• Avoid using italics in on-screen text, as italic text is hard to read.
• In documentation, use italics for specific references to the titles of manuals, books, magazines, disks, videotapes, films, audiotapes, catalogs, bulletins, and promotional literature.

Paragraphs

Be concise

• Don't add text if it's not needed.
• Use as few words as possible.
• Focus on users' tasks; write only what is necessary for users to complete them.
• Avoid unnecessary and redundant information.
• Keep tasks short.

Design text for easy scanning

• Users often scan, rather than read, text, so design the information for scanning.
• Place the most important points first and then add supplemental information if necessary.
• If you have multiple pieces of information to convey, use bulleted lists for easier scanning.
• Users read actionable text before explanatory text, so place actions first and then add explanations if necessary.
• Assume that once users have decided what to do, they immediately stop reading and do it.
• Use See Also links at the end of topics to refer users to related information. Avoid inline links whenever possible.

Avoid large blocks of text

• Keep only one topic per paragraph.
• Avoid long, complex sentences. Write so readers only have to read the sentence once.
• Keep your average sentence length less than 17 words.
• Make smooth transitions, using words and phrases such as also, in addition, moreover, consequently, however, although, for example, next, first, finally, and in contrast.
• In running text, generally avoid a string of one-sentence paragraphs.

Parallel Construction

• Use the same grammatical form for words or phrases in lists, titles, headings, or any other group of items that are related in grammatical structure or function.
• For titles, headlines, and headings, be consistent with equivalent headings throughout; that is, use nouns, noun and gerund phrases, or questions.
• Keep items in a series, list, or table parallel. Don't mix fragments and full sentences.
• Keep elements within a sentence parallel.

Parentheses

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.

• 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.

• Watch for misplaced parentheses, or an opening or closing parenthesis that lacks a partner.

• When referring to a symbol, spell out the name of the symbol and then enter the symbol in parentheses after it. For example:

  • When using an equal (=) sign, add one space on each side.

  • Wrap greater-than (>) and less-than (<) signs in parentheses rather than quotation marks.

• Use brackets to set off information already within parentheses.

• 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.

Punctuation

• Ampersands
  • Try to avoid using them, but they’re OK 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 (unless you’re hyped up on Club Mate).
  • 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
  • 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.
• Periods
  • Rule #1: Be consistent. Use a period at the end of each list item, or don’t. Just don’t do both.
  • Rule #2: Using quotation marks? Put the period inside the closing mark. Example: Damon said, “I ate all the donuts.”
  • Rule #3: 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.)
  • Rule #4: 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.
• Spacing
  • Use one space between sentences. Never two. Or three. And four is just out of the question. Don’t even.

Theme

Headings

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

The Anatomy of a Page

IMAGE

• Page Layout. 

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