Voice & Tone

Alexandria’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

• Write conversationally. Use an informal, active style, similar to the way you'd speak to someone in person.
• Multiple learning styles. – Just like in school, people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways.
• 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.
• Use visual aids. Use screenshots, GIFs, and videos to explain things along with the text.
  
  
  

Design

Formatting

Images

• Screenshot Dimensions. 1024 x 768

Mechanics

Words

Writing Guidelines

Voice

Capitals & Italics

Plurals, Possessives, Compounds

Abbreviations

Numbers

Quotations

Apostrophe | Brackets | Colon | Dash | Ellipsis | Parentheses | Period | Question Mark | Semicolon | Slash | Hyphen

Apostrophe

Brackets

Colon

Comma

Dash

Ellipsis

Parentheses

Period

Question Mark

Semicolon

Slash

Hyphen

Screenshot Guidelines

• Dimensions: 1024 x 768
  • Capture screenshots and present them on the page at their full-size.
    
  • Avoid altering their size in an image editor—let Confluence do the shrinking (if it's required), since when viewing the page, you can always click the image to view its full size.
• 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.
• Format: Save screenshots in PNG format.
• Screenshot size: Capture screenshots and present them on the page at their full-size. However, if they are bigger than 700px wide, reduce their size in Confluence to 700px.
  • Avoid altering their size in an image editor — let Confluence do the shrinking (if it's required), since when viewing the page, you can always click the image to view its full size.
• Border: Add a Confluence border around each screenshot.
• Anti-aliasing: Ensure that any area of screenshot you are capturing is anti-aliased. On Windows operating systems, this usually entails ensuring that ClearType has been activated in your Display Settings.
• 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.
• Captions: Place captions above screenshots in italicized text. Unless a screenshot description is absolutely necessary, do not use captions on screenshots incorporated into procedural steps.
• Indenting screenshots: Screenshots should not be 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 Gliffy. Don't use Snagit effects (except edge fading).

Attachments Table