Writing Guidelines

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.

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.

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.

Someone reading technical content is usually looking to answer a specific question. That question might be broad or narrowly-focused, but either way, our goal is to provide answers without distraction.

For each project, consider your audience’s background, goal, and current mood. Ask these questions:

• Is the reader a prospective user, a new user, or an experienced user?
• What is the goal of the reader? To complete a task? To research a topic?
• Is the reader in the middle of a task? Are they in a hurry? Could they be frustrated?

We don’t want to overload a reader with unnecessary information, choices to make, or complex ideas or phrases when we don’t have to. This is particularly critical when a user may be new and/or frustrated. When relevant, prime the reader with a brief outline of an article’s focus in an introductory paragraph or section, and stick to the topic at hand. Keep sentences, paragraphs, and procedural steps focused and concise.

Guidelines

• Drafting Technical Content
• Writing Technical Content
  • Stay relevant to the title
    • When a user clicks the title of an article, they expect to find the answer they want. Don’t stray too far from the title or topic at hand. Use links to make related content available. If you find you’re getting too far from the intended topic, then you may need to create a separate but related article.
  • Keep headlines and paragraphs short and easy to scan
    • Focused users often scan an article for the part that will answer their particular question. Be sure headlines are short, descriptive, and parallel, to facilitate scanning.
  • Use second-person to describe actions to a user
    • Technical content talks to users when support agents can’t.
  • Strive for simplicity and clarity
    • Be as clear as possible. Use simple words and phrases, avoid gerunds and hard-to-translate idioms or words, focus on the specific task, limit the number of sentences per paragraph. If you must include edge cases or tangentially related information, set it aside in a Before You Start list or Notes field.
  • Provide context through embedded screenshots
    • Screenshots may not be necessary for every article or process, but can be helpful to orient new users. Crop screenshots tightly around the action to focus attention.
  • Write for Accessibility

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?
  
  

Editing

We edit technical content based on three goals:

1. Digestibility

• Cut or tighten redundancies, gerunds, adverbs, and passive constructions.
• Use the simplest word.
• Limit paragraphs to three sentences.

2. Consistency

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

3. Helpfulness

• Stay conversational, using contractions when appropriate.
• Avoid qualifiers that muddy meaning.
• Express understanding when appropriate.
• Craft clear transitions from section to section to orient the reader.

Voice & Tone

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 legal documents, while also respecting their time.

We want our articles to be usable by everyone, not just advanced users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology. Assume the person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions. Also, we should assume that they haven't changed any of the default application or operating system settings.

To summarize, you should follow these guidelines:

1. Keep it short. People come to the knowledge base looking for quick solutions. They might not care about the inner workings of the tool—they just want to know what they should do to fix it. Go ahead and chop off some words. See how much can convey with fewer words. It's like poetry!
   
   
2. Keep it clear. Avoid jargon. Be specific. Use words in the title and in the article that the reader would use. If your 13-year-old nephew won't understand it, write it so that he would. See the next section for a more extensive guide.
   
   
3. Be friendly, fun and empathetic. (In short: Be human). Okay, so users don't come to support expecting fun. That's what makes this powerful. Brighten up the user's day with a little humor. But be careful not to sacrifice clarity by using fun metaphors or expressions. If you're not sure how to balance this, just write straightforward instructions and use the tone in the introduction or conclusion.
   
   
4. Tell a story. Have a beginning, a middle and an end. But don't write a novel (see guideline #1).
   • Beginning: this gives the reader some context. What is this article about and why should I care? Keep it short.
   • Middle: The instructions go here. This should answer "How do I do this?"
   • End: Are there any next steps to the article or feature? Tell the reader where he or she should go next if they want to learn more
     
     
5. Write conversationally. Use an informal, active style, similar to the way you'd speak to someone in person.
   
   
6. Multiple learning styles. Just like in school, people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways. 
   
   
7. Repetition. When you explain something in a different way with different media, you're also, obviously, repeating it which is another good way to help people remember what's important.
   
   
8. Use visual aids. Use screenshots, GIFs, and videos to explain things along with the text.

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

Reading

Desktop Apps

How To - Macros