Library
Documentation Style Guide
Writing Guidelines
COMPanion’s voice is human. It’s familiar, friendly, and straightforward. Our priority is explaining our products and helping our users get their work done so they can get on with their lives. We want to educate people without patronizing or confusing them.
- Accuracy. Our first and foremost concern is that we present the correct information in a truthful way.
- Clarity. We try to avoid legal jargon and overly formal wording. Our users need to understand the agreement they’re making with us.
- Succinctness. We want our users to read and understand our documentation, while also respecting their time.
Technical content talks to users when support agents can’t. We write and edit this content based on these goals:
Content principles
- Start with user needs
- Write in a way that suits the situation. Ask yourself: Who is going to read this? What do they need to know? How might they be feeling?
- Help people find the information they need quickly and easily. Guide them through the process.
Do the hard work to make it simple
- Use plain language and simple sentences.
- Choose clarity over cleverness.
- Stay conversational, using contractions when appropriate.
- Keep headlines and paragraphs short and easy to scan.
Write for everyone
- Respect the complexity of our users’ experiences.
- Be willing to be surprised about who’s reading your work.
Build trust
- Talk like a person.
- Tell the truth.
- Use positive language and concrete examples.
Be consistent
- Use the labels and terminology used by COMPanion.
- Use specific, active verbs for certain tasks.
- Choose basic words and phrases to facilitate consistency across translated content.
Start small and iterate
- Make sure your content works for users. Don’t be afraid to scrap what’s there and start over.
- Write a draft, test it out, gather feedback, and keep refining.
As you write, consider the following:
- Will this language make sense to someone who doesn’t work here?
- Can someone quickly scan this document and understand the material?
- If someone cannot see the colors, images or video, is the message still clear?
- Is the markup clean and structured?
- Mobile devices with accessibility features are increasingly becoming core communication tools. Does this work well on them?
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:
- Click the Accounts menu at the top of the page.
- Click Passwords in the submenu.
- Scroll down to Two-Factor Authentication, and then click the Enable Two-Factor Authentication link.
To add a repository:
- Go to Admin > Repository List > Add repository.
- Select a Repository type from the dropdown menu.
- 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
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
Heading 1
- 30px
Heading 2
- 22px
Heading 3
- 18px
Heading 4
Heading 5
Heading 6
Palette
Core
- Primary #102742
- Secondary #29A7A7
- Accent #BF1E65
Tints and Shades
- Dark #000000
- Medium #3B3738
- Light #F1F6FC
Grays
- Dark Gray #3B3738
- Medium Gray #A3A2A3
- Light Gray #EFEFEF
- White #FFFFFF
Fonts
- Headings: Weekly
- Body: Arial
Headings
Heading | Size | Use | TOC | Notes |
---|---|---|---|---|
Heading 1 | 30px | X | ||
Heading 2 | 22px | Yes | ||
Heading 3 | 18px | X | ||
Heading 4 | 15px | X | ||
Heading 5 | 18px | X | ||
Heading 6 | 14px | X |
The Anatomy of a Page
IMAGE
- Page Layout.
Structure
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Pages are formatted as such:
Heading 1: Title | (image - g map, 16px) Location (bold, superscript, right) |
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
- Cross Referencing
- Visit the Microsoft Accessibility Website to learn more.
- 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.
Steps & Instructions
- Choosing Bullets or Numbers
- Maintain Parallel Construction
- Punctuating and Capitalizing Items
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.
Examples and Quotes
Callout Boxes
Tip
Info
Note
Informs users that failure to perform or avoid a specific action could result in a loss of data. For example: Activating a refreshed sandbox replaces the existing sandbox with the refreshed version. This permanently deletes the existing version and all data in it.
Warning
Informs users that failure to perform or avoid a specific action could result in a loss of data. For example: Activating a refreshed sandbox replaces the existing sandbox with the refreshed version. This permanently deletes the existing version and all data in it.
Naming Schemes
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
Confluence is organized the way the program is organized. The primary modules are listed in the menu at the top:
Some content should reasonably appear in multiple page trees. However, because no two pages can have the same title,
Each module has a page template.
- You'll want to work with the Confluence sidebar most of the time.
Editor Pages (Hidden)
- On the bottom left, go to Space Tools > Reorder pages. This is where you'll see all of the pages that aren't in the Home page tree, including the Editor's Pages (Hidden).
Links
Support Portal | |
---|---|
Alexandria v6 | http://www.companioncorp.com/mediawiki/index.php/Main_Page |
Alexandria v7 | http://support.companioncorp.com/display/ALEX/Support |
KeepnTrack | http://support.companioncorp.com/display/KnT/Support |
Textbook Tracker v4 | http://www.companioncorp.com/mediawiki/index.php/Textbook_Tracker |
Textbook Tracker v7 | http://support.companioncorp.com/display/TT |
Space Directory: http://support.companioncorp.com/spacedirectory/view.action
Each app has a separate library space.
Shortcuts
Key | Action |
---|---|
. | Opens the Theme Press menu |
z | Opens or hides the Confluence sidebar and header. |
Theme Architect
We use Brikit Theme Press to design the Support Center.
- Library
- Mobile
- TestAlexandria (Ashley's Home)
- Testing
Space | Theme | Menu | Default Page Layout | Other |
---|---|---|---|---|
Alexandria | Alexandria | Alexandria | ||
Alexandria Library | Alex | ALIB | ALIB | |
COMPanion | COMPanion | COMPanion | ||
KeepnTrack | KnT | KeepnTrack | ||
KeepnTrack Library | KnT | KeepnTrack | KLIB | |
Testing | Testing | Alexandria | ||
Textbook Tracker | TextbookTracker | Textbooks | ||
Textbook Tracker Library | TextbookTracker | Textbooks | ||
Theme Press Default | ||||
Theme Press Demo | Demo | |||
UX Team | N/A | N/A | Brikit Theme Press isn't being used on this space. The content will eventually be moved to Confluence Cloud. |
Brikit | Link | Notes |
---|---|---|
Documentation | http://www.brikit.com/display/documentation/Home | Read through this documentation to learn how Brikit works with Confluence. |
A2
Space Architect
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
- Command + M, or go to + and choose Files and Images.
- Search on other pages
- Enter your search term(s).
- 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.
- 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.
- If you're looking for
- I
- Scan the results to find the image you're looking for.
- 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
Alex | X | Module | Location | Secondary Location | |
---|---|---|---|---|---|
Alexandria | 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.
Brand
- Alex
- KnT
- TT
- COMP
Type
- C - Content
- D - Documents
- G - Graphic
- S - Screenshot
- V - Video
Module
- Tools
- Preferences
- Circulation
- etc.
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
Accessibility
Technical Documentation
- Write The Docs - Documentation Principles (Guide)
- 24 Ways - The Construction of Instruction
24 Ways - Kill It With Fire! What To Do With Those Dreaded FAQs
User Experience
Vertical Lists
Desktop Apps
Windows
- Screen capturing and annotation
- Vector design and illustration
- SVG editor
- Can be used for wireframing
- Licensed to mia@companioncorp.com
Adobe XD (free)
- Wireframing tool
GIMP (free)
- Find coordinates to create an image map.
iOS
Preview (free)
- Screen capturing and annotation
- Wireframing tool
- SVG editor
Adobe Illustrator
- Vector design and illustration