Library
Alexandria Style Guide
Alexandria Style Guide
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:
- 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!
- 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.
- 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.
- 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
Abbreviations
Contractions
Capitals & Italics
Plurals, Possessives, Compounds
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
Page Titles
Headings
- Use H2 for main headings.Do not use H1.
- Use sentence case subheadings (H3 or H4).
- Headings 5 and 6 are in an accent color. Use these to bring attention to particular sections.
Heading 3
Heading 4
Heading 5
Heading 6
Text Formatting
Use italics to indicate the title of a long work (like a book, movie, or album) or to emphasize a word.
- Harry Potter and the Chamber of Secrets
- Ashley really loves Alice in Wonderland.
Use italics to cite an in-app element.
Use italics for the names of windows and dialog boxes.
- The Available Updates window shows...
Use italics when citing an example of an in-app Alexandria element:
- When you're all done, click Send.
- The familiar A/B testing variables—Subject line, From name, and Send time—have now been joined by Content, and up to 3 combinations of a single variable can now be tested at once.
Use italics when referencing anything the user will type.
Step-by-Step Instructions
Use bold when referencing in-app element, button and navigation labels customers will click on or interact with:
- 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.
Don’t use underline formatting, and don’t use any combination of italic, bold, caps, and underline.
Left-align text, never center or right-aligned.
Leave one space between sentences, never two.
Links
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.
Link "imperative sentences", as long as they're not extremely long, to prompt action and tell the reader what happens if they click that link:
- RIGHT: You can download Second Life
- WRONG: You can download Second Life
Cite Knowledge Base articles as follows:
- WRONG: Read this article for information on attachments.
- WRONG: For more information see Avatar attachments.
- RIGHT: 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.
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.
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.
- Capture screenshots and present them on the page at their 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).