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:

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

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

Voice and Tone

Word Choice

Can, Could, May, Might, Must, Should

Avoid the modal verbs could, may, might, and should in technical documentation. Modal verbs are ambiguous and leave the reader wondering what to do.

• Can means the ability to do something. Avoid could.
• May means permission to do something. Avoid may. We rarely indicate permission to do something in the documentation. Use can for the ability to do something.
• Might means it’s possible to do something. Avoid might and use an imperative instead. For example, instead of saying “You might consider XYZ” use “Consider XYZ”.
• Must means it’s necessary to do something. Avoid should. Use must for necessity or rephrase as “Salesforce recommends...” to tell a customer to do something.
  
  

Terminology

Mouse

• Click means click the left mouse button.
• Right-click means click the right mouse button.
• Don’t use click on: Click Merge to finish.
• When referring to the mouse, use pointer.
• Use drag by itself as a verb. The action of dragging includes dropping the item in place. For example: Drag the item to another day of the week.
• Use hover instead of mouse over to describe moving the mouse pointer over an icon, field, or button. Write hover over instead of hover your mouse pointer over.
• Don’t use mouse terminology when describing actions users perform in a mobile app. See Mobile Interfaces and Documentation on page 26.

Palette

• Primary #5F51A2
• Primary #EF3C45
• Primary #F1F6FC
• Primary #3B3738
• Primary #A3A2A3
• Secondary #FEBC26
• Secondary #4FC2C1

Headings

• Heading 1

• Heading 2

• Heading 3

• Heading 4

• Heading 5

• Heading 6

Fonts

• Headings: Weekly
• Body: Arial

Structure • Links • Lists • Instructions • Tables • Examples • Callout Boxes

Structure

Lists

Links

1. Cross Referencing
1. For  more information, visit the Microsoft Accessibility Website.
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.)