Writing Guidelines

• Content Principles (Summary)
• 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:

• Would this language make sense to someone who doesn’t work here?
• Could someone quickly scan this document and understand the material?
• If someone can’t 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?

We edit technical content based on three goals:

• Digestibility
• Cut or tighten redundancies, gerunds, adverbs, and passive constructions.
• Use the simplest word.
• Limit paragraphs to three sentences.
• Consistency
• Use the labels and terminology used by Bluehost.
• Use specific, active verbs for certain tasks.
• Choose basic words and phrases to facilitate consistency across translated content.
• 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

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.

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

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. Simply follow the general page name suggestions discussed above.

Headings

• Use H2 for main headings.Do not use H1. 
• Use sentence case subheadings (H3 or H4).

  • Heading 3

  • Heading 4

• Headings 5 and 6 are in an accent color. Use these to bring attention to particular sections.
  

  • 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 in-app elements, windows, and dialog boxes.

• We've added a scannable barcode to Patron Details.
• The Available Updates window shows...
  

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.

Step-by-Step Instructions

Use bold when referencing in-app element, button and navigation labels customers will click on or interact with:

Example:

1. Click the Accounts menu at the top of the page.
2. Click Passwords in the submenu.
3. Scroll down to Two-Factor Authentication, and then click the Enable Two-Factor Authentication link.

To add a repository:

1. Go to Admin >  Repository List > Add repository.
2. Select a Repository type from the dropdown menu.
3. 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.
   
   

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.

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.

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.
  
  

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

Labels

Labels are very important for categorizing and searching. Therefore we have a standard set of page labels to be included on each page. Labels are used to categorize pages, not to repeat a page title. Searching in Confluence is aggregated by page title first, then labels, then document contents. The following are Knoweldge Base labels. Additional label conventions may be used by Private Spaces.

Never use two-word labels, as they are added as two separate label entries. For example "In Progress" is added as a label for "In" and a label for "Progress", which is not helpful when it comes to searching. If you absolutely must use a two-word label, type it as one word by inserting a hyphen between words (i.e. in-progress).

Page Titles

• Use brief, but specific, informative titles. Titles should give context when possible.
• Use sentence-style capitalization; do not end with a period or colon.
• Use a gerund to begin section titles. Examples: Configuring, Managing, Starting.
• Use descriptive titles for tables and figures titles. Do not number tables or figures. Do not (in general) add titles for screen shots.
  

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.