Cornerstone

Content Style Guide

Guidelines for every rackspace.com writer

Acronyms

As a general rule, when you first introduce an acronym on a page, spell out the entire phrase and include the acronym afterward in parenthesis, like this: Content Delivery Network (CDN).

Now, it’s time for the exceptions.

Exception 1: If the first instance of an acronym is in a header, use just the acronym. Then, define the acronym in the content that follows, like this:

Get fast page loads with the Akamai CDN

The Akamai Content Delivery Network (CDN) is a powerful…

Exception 2: For acronyms that are common to our industry, don’t spell out the individual words. Examples of common acronyms include:

  • Languages: HTML, CSS, PHP, SQL
  • Measurement units: KB, MB, GB, TB, Gb, Mb, Gbps, Mbps
  • Common job titles: VP, CIO, CTO, DBA
  • As-a-service offerings: SaaS, DBaaS, PaaS, IaaS
  • I/O
  • RAID
  • RAM
  • SSD
  • SLA
  • API
  • REST/RESTful API
  • SDK
  • SSL
  • IP address
  • DNS
  • CPU
  • PCI compliance

Do spell out these common acronyms. Testing shows that our users don’t immediately recognize these terms.

  • Direct-Attached Storage (DAS)
  • Storage Area Network (SAN)
  • Network Area Storage (NAS)

Commas

Use serial (or Oxford) commas to convey a list of three or more items or concepts—for example, “Our engineers understand how to anticipate failures, prevent bottlenecks, and maximize performance.”

Do not use a comma to separate a two-item series—for example, “Our engineers understand how to anticipate failures and prevent bottlenecks.”

Use a comma before the preposition that connects two sentences—for example, “Your sites have to stay up and running, but you don’t want the hassle of dealing with infrastructure and servers.”

Contractions

Because we’re using a friendly and conversational tone, you can use common contractions freely in your writing.

  • You’re, you’ll, you’d, you’ve
  • It’s (remember that “its” is the correct form for possessives!)
  • We’re, we’ll, we’d, we’ve
  • They’re, they’ll, they’ve
  • That’s
  • Who’s (remember that “whose” is the correct form for possessives!)
  • What’s

Do not use uncommon contractions, such as “what’ll” or “musn’t.”

Dashes

You’ll use several different kinds of dashes in your copy: emdashes (—), endashes (–), and hyphens (-). Each has its own specific use, so make sure you understand the differences.

Em-dashes

An emdash (—) is the widest-width dash. To add variety to your copy and make it more readable, judiciously use emdashes in the following situations:

  • Instead of commas to offset a parenthetical phrase. For example, “Cloud Backup uses space-saving technologies—like block-level compression and de-duplication—to make backups more efficient and reduce storage costs.”
  • Instead of a semicolon to connect two sentences. For example, “Accidentally messed up networking on your server? No problem—every Cloud Server has out-of-band console access.”
  • To introduce a phrase with added emphasis. For example, “Choice is a big deal—especially when it comes to where you run your databases, applications, and websites.”

Do not insert spaces around emdashes. The keyboard shortcut to insert an emdash on a Mac is Shift+Option+-. On Windows, the shortcut is Alt+0151.

En-dashes

An endash is slightly wider than a hyphen. Use endashes to indicate ranges for values that display in a table—for example, “2GB – 4GB.” For ranges outside of a table, use to and/or between—for example, “between 2GB to 4GB.”

Do not insert spaces around en-dashes. The keyboard shortcut to insert an en-dash on a Mac is Option+-. On Windows, the shortcut is Alt+0150.

Hyphens

A hyphen is the narrowest dash. Use a hyphen to join two to three words that work together to modify a noun (compound modifier)—for example, “fastest-growing cloud platform” or “64-bit operating system.”

Do not hyphenate:

  • Adverbs that precede nouns. For example, “newly designed interface” is correct, but “newly-designed interface” is not.
  • Terms that are not compound modifiers. For example, “Our on-demand servers feature…” is correct, but “Our servers are available on-demand,” is not.
  • Trademarked terms. For example, “platform built on OpenStack” is correct, but “OpenStack-based platform” is not.

Headers

Headers are a really important aspect of the content we write. They alert readers to the content that a page contains, and (hopefully) compel them to keep reading for more details.

When writing headers:

  • Be powerful. Focus on the product features that are most important to your reader.
  • Be succinct. Use the fewest words possible, while still conveying your thought in a compelling way.
  • Be focused. Don’t cram a bunch of ideas into one header. Choose the one or two features that are most important, and save the others for further down the page.
  • Be specific. Use facts and data when you can.
  • Consider SEO. Headers play an important role in optimizing content for search engines.

Latin Phrases

Do not use e.g. (use “for example”) or i.e. (use “that is”). These abbreviations don’t localize well, and many readers won’t know what they mean.

Lists

Use bullets for any list that doesn’t cover step-by-step instructions. Use bold text for any introductory text, and end the introductory text with a period—like this:

  • Feature one. This is a feature.
  • Feature two. This is a feature.
  • Feature three. This is a feature.

Use numbers for any list that covers step-by-step instructions—like this:

  1. Do this first.

  2. Then do this.

  3. Then do this.

Paragraphs

Keep paragraphs short (2 – 4 sentences) and focused on a single topic. Make sure all of the sentences in a paragraph relate to each other, and logically flow from the topic sentence to more detailed information.

Product Names

Always use the exact names of our products, without modification—for example, “Cloud Databases” not “Cloud Database.” Never turn a product name into a compound modifier—for example, “OpenStack-based platform” is incorrect.

Sentences

Avoid using lots of long sentences. Short sentences are good. But mixing short and long sentences is ideal, and helps the copy to flow better.

Spellings

Some words have multiple common spellings. For consistency, use the following conventions:

  • 24x7x365
  • backup (noun) or back up (verb)
  • colocation
  • data center
  • ecommerce (capped: Ecommerce)
  • Internet
  • login (noun)
  • log in or log into (verb)
  • name server
  • Rackers
  • subdomain
  • webpage
  • website

Verbs

To make your writing clear and concise, avoid using the weak verbs “is” and “has” in most of your copy. That includes all forms of these words (“are,” “have,” “am,” “be,” etc). Instead, find more active substitutes—for example:

Instead of this: Rackspace is the industry leader.

Say this: Rackspace leads the industry.

Voice

Almost every writer knows that it’s important to write primarily in the active voice. But what does that really mean?

Writing in active voice means constructing a sentence so that the subject performs the action. In passive voice, the subject is the target of the action. For example:

Passive voice: Your team is extended by us, as we gain a comprehensive understanding of how your application works.

Active voice: We become an extension of your team, with a comprehensive understanding of how your application works.

You probably agree that the active version is more powerful and easier to read. In some cases (though not in this particular case), writing in passive voice also obscures a sentence’s meaning. That’s why it’s almost always preferable to write in active voice.

There are some cases where passive voice is appropriate. So, use passive voice when you need to—just be judicious.

Units of Measurement

Do not put a space between a unit of measurement and its value—for example, 4GB is correct (4 GB is not).

You

Because we write in a friendly and conversational tone, it’s perfectly fine to use the word “you” to talk to your reader. That said: Don’t overuse it. When you find yourself saying “you” over and over again, reconstruct your sentences for more variety.