Follow

Maven Style Guide

Screen_Shot_2021-06-02_at_3.48.29_PM.png

Welcome to the Maven Online Writing Style Guide. The point of this guide is to help you, the author, have a solid idea of what to do and where.

Grammar and Punctuation

     1. British English

     2. Apostrophes 

     3. Capitalization

     4. Commas

     5. Hyphens

     6. Dashes

     7. Lists

     8. Numbers

     9. Quotation Marks/Quotes

     10. Titles

     11. Headings and Captions

Formatting and Layout

     12. Formatting

     13. Videos

     14. Pull Quotes and Block Quotes

     15. Tables

     16. Sneak Peeks

     17. Images

     18. Headings

     19. Organization and SEO

     20. Crafting Titles (H1)

     21. Links

     22. Citations

     23. Spammy Elements

     24. Reader-Trust-Affecting Errors

     25. Additional Helpful Resources

This Style Guide is a blend of the Chicago Manual of Style (CMS) and American Psychological Association (APA) guidelines. The CMS is more widely used for online writing and publishing for a larger audience, whereas APA is primarily geared toward science and research. CMS is also the most comprehensive and nuanced. Many of the guidelines we follow are from the CMS, but occasionally we revert to APA (e.g. APA title case and citation style).

1. British English

Policies around British and English standards:

  • Spelling and Punctuation: When it comes to using British spelling (such as "colour"), be consistent. You may choose to leave punctuation outside of quotes (such as 'Find your way'.) Similarly, be consistent with the Oxford comma; either use it or don'tbut don't mix the two!
  • Grammar: "That" and "which" may be used interchangeably for restrictive relative clauses (e.g. "He raised the finger that was hurt" or "He raised the finger which was hurt").

The Punctuation Guide denotes some of the key differences between American and British punctuation.

 

Screen_Shot_2021-06-02_at_3.49.35_PM.png

Example Key

Correct examples are underlined.

2. Apostrophes

Dates: It happened in the 1960s, not the 1960's. It also happened in the '70s, not the 70s or the 70's.

Possession: Use an apostrophe after the "s" at the end of a plural noun to show possession: e.g. "parents' mistakes."

When it comes to adding possessive apostrophes to singular proper nouns that end in "s," it's up to you whether to add a second "s" after the apostrophe. As long as you're consistent, either style is correct.

  • "Charles Dickens' novels" and "Charles Dickens's novels"
  • "Kansas' gun laws" and "Kansas's gun laws"
  • "James' pink lawn flamingo" and "James's pink lawn flamingo"

Additional Scenarios

  • It's or its? "It's" is a contraction of "it" and "is" (it's a little muggy today). "Its" is the possessive (its color offends me).
  • What if the thing belongs to more than one person? No matter how long the list of owners is, make only the final name possessive: e.g. "señor and señorita's reservation."
  • The plural form of lowercase letters is formed with an apostrophe to prevent misreading (e.g. "Mind your p's and q's"). 
  • The plural form of uppercase letters does not require an apostrophe (e.g. She got all As.).
  • Dos and don'ts: Do's and don'ts? Incorrect. Do's and don't's? Incorrect. Dos and don'ts? Correct!

3. Capitalization

Capitalizing Titles

APA capitalizes all words that are important and affect readers' understanding, those that are four letters or more, and verbs. Capitalize My Title can be a helpful tool, although its accuracy varies. You will often need to capitalize four-letter words and two-letter verbs manually.

  • "From" and "with" should be capitalized.
  • Two-letter verbs such as "is" and "be" should be capitalized in a title and in H2s/H3s (unless the heading is in sentence form, in which case it includes terminal punctuation).
  • Hyphenated two-word modifiers should be capitalized (e.g., “Kid-Friendly Activities to Do on a Sunny Day”).

Note: APA allows for the capitalization of "major" words in titles and headings. While it isn't technically incorrect to leave those words uncapitalized, it often looks better to capitalize them.

  • "Growing up Without a Father" vs. "Growing Up Without a Father"
  • "How to Find out If She Likes You" vs. "How to Find Out If She Likes You"

Note: Similarly, it is up to your discretion whether to capitalize the middle word in a hyphenated three-word modifier. While APA prefers it be capitalized, it often looks better uncapitalized.

  • "Side-By-Side Comparison" vs. "Side-by-Side Comparison"
  • "Step-By-Step Guide" vs. "Step-by-Step Guide"

Proper Nouns vs. Common Nouns

Oftentimes, random words such as "Spaghetti Squash" are capitalized in an article. "Spaghetti squash" is a common noun and should not be capitalized. If you're ever unsure about whether or not something should be capitalized, Wikipedia and Merriam-Webster are usually spot-on and can be used to answer any questions.

Race and Ethnicity

When discussing race or ethnicity, capitalize accordingly. Examples:

  • “In 1992, Mae Carol Jemison became the first Black woman to go to space.” 
  • "Wayne Newton, a Native American singer with Cherokee and Powhatan roots, was once the highest-paid act in Las Vegas."
  • "Rachel Dolezale—a White woman who pretended to be Black—was charged with welfare fraud in 2018.” 
  • "The National Association of Latino Arts and Cultures (NALAC, for short) is a nonprofit organization dedicated to supporting Latinx creatives and cultural workers."

From APA’s page on Racial and Ethnic Identity: “Whenever possible, use the racial and/or ethnic terms that your participants themselves use. Be sure that the racial and ethnic categories you use are as clear and specific as possible.” For an in-depth guide to the spelling and capitalization of racial and ethnic terms, check out the APA Style page on Racial and Ethnic Identity.

God and He

"God" and "He" should be capitalized when it refers to the singular Judeo-Christian god, as in "In the Old Testament, God has a lot of opinions." When "god" is used to refer to any other god, it is usually not capitalized, as in "I sketched the god Shiva" or "I was doing research on Greek gods."

Common Names (Species)

While capitalized and uncapitalized common names of species are both correct, it is preferred that you capitalize the entire common name. Examples:

  • For a pet site: Use German Shepherd rather than German shepherd or Golden Retriever rather than golden retriever (see American Kennel Club publications). Types of breedssuch as pit bulls and shepherdsare not capitalized.
  • For a nature site: Use White-throated Swift rather than white-throated swift. Birders and people who write about birds tend to capitalize all words in a common name of the species (see Audubon Society publications).
  • For a home and garden site: Use Lily of the Valley rather than lily of the valley.

Geography

  • Compass points: Points and terms derived from compass points are kept in lowercase if they indicate a direction or location (e.g., "directed toward the south," "a north squall," "the northeast of Michigan," "northwesterly," "southern Africa" [vs. "South Africa"]).
  • Regions of the world and national regions: Capitalize terms that denote regions of the world or a country, for example, "I live in east Japan" (not "East Japan") or "My family is from the South" (not "the south"); the East (of the United States), the Middle East, the Eastern Hemisphere; the North (of Japan), Northern California, the North Atlantic; the South (of France), Southeast Asia, the Southwest; the West (of Europe), the Western Hemisphere, the West Coast.
  • Undetermined items: For items that are unclear after extensive research, opt for lowercase. Regional, political, and historical contexts vary, so the capitalization of certain items may be at your discretion.

Capitalization Following a Colon

Capitalize the word that follows a colon if what follows the colon is a complete sentence. If it is not a complete sentence, do not capitalize it:

  • Freud wrote of two urges: an urge toward union with others and an egoistic urge toward happiness.
  • Freud wrote of two urges: An urge toward union with others and an egoistic urge toward happiness.
  • They have agreed on the outcome: Informed participants perform better than do uninformed participants.
  • They have agreed on the outcome: informed participants perform better than do uninformed participants.

4. Commas

Compound Sentences

Compound sentences are when two sentences are joined together either by a coordinating conjunction (such as but, and, or, so, yet, etc.) or appropriate punctuation (such as a semicolon). For instance, "I went to the store, and I brought my jacket along." "I went to the store" and "I brought my jacket along" are two independent clauses or complete sentences, joined together by the coordinating conjunction "and."

  • Correct: "I went to the store, and I brought my jacket along."
  • Incorrect: "I went to the store and I brought my jacket along." This is an example of a run-on sentence.
  • Incorrect: "I went to the store, and bought ice cream." This is called a comma splice. This is a comma splice because "bought ice cream" is not an independent clause; therefore, it shouldn't be offset with a comma. "Bought ice cream" is the second half of a compound predicate.

Note: If the clauses are very short and closely connected (and aren't part of a series), the comma may be omitted: e.g. "Raise your right hand and repeat after me."

Note: "Because" is not a coordinating conjunction, and you typically don't want a comma in front of it (except in instances where you use a comma to avoid confusion). You can find more examples at Your Dictionary.

Compound Sentences With Introductory Phrases

Introductory and prepositional phrases: If your sentence begins with an introductory clause or a prepositional phrase, offset it with a comma. The exception is a single word phrase. If you see something like, "Today I went to the store," we'll say that the comma is optional. The Editor's Blog has additional examples.

  • "If you accept my apology, we can get back to business." Correct 
  • "He's not the best person for the job, if you want my opinion." Correct. "If you want my opinion" is an example of a nonrestrictive clause, meaning it doesn't change the meaning of the sentence. If the clause is restrictive, you should not have the comma.
  • "On Saturday, we went to the movies." Correct. A single word or very short introductory phrase does not need a comma, except in order to avoid confusion. In order for us to maintain consistency, all introductory phrases should be offset with commas regardless of their length.

In some cases, the correct use of commas within a sentence may not be visually appealing. Consider the following examples (the second way is preferred):

  • Technically correct: "After riding his bike around the block twice, Rob was sweating profusely, and, when he got home, he really needed some water." While this punctuation is technically correct, the onslaught of commas does not look particularly appealing. In this very particular case, it's okay to omit the comma.
  • Correct (and preferred): "After riding his bike around the block twice, Rob was sweating profusely, and when he got home, he really needed some water." While there are several ways to punctuate this correctly, this way looks the cleanest and is correct.

In some cases, the correct use of commas within a sentence may not be visually appealing. Consider the following examples (the second way is preferred):

  • Technically correct: "After riding his bike around the block twice, Rob was sweating profusely, and, when he got home, he really needed some water." While this punctuation is technically correct, the onslaught of commas does not look particularly appealing. In this very particular case, it's okay to omit the comma.
  • Correct (and preferred): "After riding his bike around the block twice, Rob was sweating profusely, and when he got home, he really needed some water." While there are several ways to punctuate this correctly, this way looks the cleanest and is correct.

Direct Addresses

Whenever you address a person or group directly, that direct address needs to be offset by one comma if at the beginning or end of a sentence, or framed by commas if it is in the middle of a sentence. So:

  • "Get in the chopper, Arnold!" 
  • "Arnold, get in the chopper!" 
  • "Thank you, Arnold, for saving us." 
  • "Thanks Arnold!" Incorrect
  • "Thank you Arnold for saving us." Incorrect

Imperatives: Either a comma or no comma is fine. Just be consistent.

  • Call all of your close friends and invite them over to a tea party!
  • Call all of your close friends[,] and invite them over to a tea party!

Note: Omit the serial comma if it precedes an ampersand. This is a rare case that should only come up in titles that would otherwise be too long, e.g., "Loire Valley Wine Tasting in Saumur, Chinon, Amboise & Azay-le-Rideau." Otherwise, "and" is always preferred. For more information on when to use ampersands, check out this article.

Conjunctions

Conjunctions connect sentences, clauses, or words within a clause. Some simple, one-word conjunctions include "and," "but," "if," "or," and "though."

  • Beginning a sentence with a conjunction: It is perfectly fine to begin a sentence with a conjunction (despite the widespread belief that it is wrong to do so). 

    • Take care when beginning a sentence with "but." This only works if the idea it introduces truly contrasts with the previous sentence. To see if "but" is appropriate, try substituting it with "and." If "and" can be substituted, "but" is (almost always) the wrong word.

Geographic References

A geographic reference that includes a comma needs a comma after the final piece of the geographic location. For instance, "I live in Mobile, Alabama, with my parents" is correct. "I live in Mobile, Alabama with my parents" is incorrect. The Punctuation Guide offers additional examples.

Restrictive and Non-Restrictive Clauses

Restrictive and non-restrictive clauses, such as "that" and "which": The basic rule of thumb in American English is that if a phrase is necessary (restrictive), you should use "that," and if a phrase is unnecessary (non-restrictive), you should use "which." Oxford Dictionary wrote a great article explaining this in more detail.

A restrictive relative clause gives us essential information about the noun it precedes. Commas are not used to precede this type of clause:

  • Correct: "She extended the paw that was hurt." This information is necessary. Imagine the sentence as "She extended the paw." If the clause is left out, the meaning of the sentence is affected or changed. It doesn't make any sense; therefore, the phrase is necessary. As a necessary phrase, it gets a "that" and should not be offset with a comma.
  • Correct in British English only: "She extended the paw which was hurt." In British English, "that" and "which" are both correct. (In American English, only "that" is correct in this scenario.)
  • Incorrect: "She extended the paw, which was hurt." Knowing which paw she extended is necessary information so it should not be offset with a comma. "Which" is also used incorrectly per American English.

Non-Restrictive Relative Clause

A non-restrictive relative clause contains extra information or additional details. If left out, the meaning of the sentence is not changed. These clauses are preceded by a comma (which sets off the information). "That" is never used to introduce this type of clause in British AND American English, but "which" is acceptable:

  • Correct: "She extended her paw, which was hurt." It's not necessary to know that she hurt her paw. It's extraneous information that doesn't change the sentence. Therefore, it gets a "which" and must have a comma.
  • Incorrect: "She extended her paw which was hurt." A "which" phrase is almost always offset with a comma because "which" generally indicates extraneous information.
  • Incorrect: "She extended her paw that was hurt." The fact that she hurt her paw isn't necessarily important. Additionally, this sentence's phrasing means that she had previously hurt her paw, which is likely not the intended meaning of this sentence.

More examples:

  • Restrictive: She was eating the food that was kosher.
  • Non-restrictive: They entered the graveyard, which was haunted.

Coordinate Adjectives vs. Cumulative Adjectives (Separating Adjectives With Commas)

  • When you have a string of adjectives, you often separate them with commas, as in "He's tall, dark, furry, and handsome."
  • If each adjective separately modifies the noun, you insert a comma, as in "a heavy, bulky box," since both "heavy" and "bulky" modify "box." 
    • A quick way to know for sure: If you can rearrange the adjectives or insert "and" between them and the sentence still makes sense, you need a comma. "Bulky, heavy box" and "heavy, bulky box" both work, as do "bulky and heavy box" and "heavy and bulky box," so that comma is necessary.
  • On the other hand, cumulative adjectives have a relationship to each other, too, not just the noun. In "exquisite custom houseboat," "custom" modifies "houseboat" (they become a unit), and then "exquisite" modifies "custom houseboat." Apply the test and rearrange: "custom exquisite houseboat" no longer makes sense, does it? So you can leave the comma out.

5. Hyphens

Hyphens should be used to join two or more words together, such as "eye-opener" or "free-for-all." They should also be used to join multi-word modifiers.

Note: Hyphens should not be used in place of an em dash. For example:

  • Correct: "We adore gritsas long as they are made rightand this is exactly right."
  • Incorrect: "We adore grits - as long as they are made right - and this is exactly right."

Compound Adjectives

When placed before a noun, phrasal adjectives should (usually) be hyphenated to avoid misleading the reader. In addition, compound adjectives that consist of two words joined together to modify a single word (a.k.a. multi-word modifiers) are hyphenated. For instance:

  • "I saw a man-eating alligator" vs. "I saw a man eating alligator." (The former is an alligator with an appetite for human flesh, the second is the opposite!)
  • "Small-animal hospital" vs. "Small animal hospital" (The former is a hospital dedicated to treating small animals. The latter is an animal hospital that happens to be small.)
  • "She loves 19th-century architecture" vs. "She loves 19th century architecture" BUT "The 19th century saw the rise and fall of many architectural styles" vs. "The 19th-century saw the rise and fall of many architectural styles."

Note: Do not hyphenate "ly" words. For instance, "the greatly-exaggerated tale" is incorrect; "the greatly exaggerated tale" is correct. "Greatly" is an adverb that modifies the word that follows it. Therefore, we do not need to hyphenate "greatly" and "exaggerated" because we know that by the sake of being an adverb, "greatly" modifies "exaggerated."

Additional resources: APA has a succinct and helpful guide to compound adjectives.

Exceptions

There are, of course, exceptions. Something like "chocolate chip cookie" probably doesn't need to be hyphenated (and over-hyphenation can look bad). The general best practice is that if there's any way the word could be misconstrued, you should probably include a hyphen (e.g. the "high school kid" and the "high-school kid").

Spelling

Multiple variations: For words that can be spelled multiple ways (such as "crock pot," crock-pot," or "crockpot"), pick one variation and use it consistently.

"A" or "an" before acronyms and initialisms: An acronym is an abbreviation formed from the letters of a grouping of words and pronounced as one word (e.g. NATO). An initialism is an abbreviation of initial letters pronounced separately (e.g. FBI). We generally use "a" before consonants and "an" before vowels, but with acronyms and initialisms, it depends on how they are pronounced. See examples below:

  • "An FBI agent" vs. "a FBI agent"
  • "An MIT grad" vs. "a MIT grad"
  • "A UFO" vs. "an UFO"
  • "A NATO emergency" vs. "An NATO emergency"
  • "An AIDS patient" vs. "a AIDS patient"

Sometimes these abbreviations can be said either way, in which case either "a" or "an" could be correct. For example, "a NES console" and "an NES console" are both acceptable. 

Note: When spelled out, these abbreviations do not always need capitalizing ("Federal Bureau of Investigation" vs. "unidentified flying object").

Additional Resources

APA has a succinct and helpful guide to compound adjectives.

Pro Tip

If you're unsure if a word should be hyphenated, check to see what Merriam-Webster's Online Dictionary and Wikipedia have to say.

6. Dashes

Em Dashes ()

Em dashes sometimes appear as "--." It's preferable that you change "--" to the em dash "." Em dashes should not have spaces on either side of the word. For instance:

  • Correct: "Upon discovering the errorsall 124 of themthe publisher immediately recalled the books."
  • Incorrect: "Upon discovering the errors all 124 of them the publisher immediately recalled the books." 

Note: Avoid em dashes in titles because they take up too much horizontal space.

Em Dash Shortcut

On a Mac, the keyboard shortcut for an em dash is 'option' + 'shift' + '-'

En Dashes (–)

En dashes are primarily used to connect numbers, and they signify "up to and including"/"through." For example:

  • Read chapters 4–7 by Monday
  • Part-time employees work 20–30 hours per week
  • Severus Snape (1960–1998)

If "from" precedes the first number, "to" should be used rather than an en dash.

  • Correct: "Buffy the Vampire Slayer ran from 1996 to 2003"
  • Incorrect: "Buffy the Vampire Slayer ran from 1996–2003"

If "between" precedes the first number, "and" should be used rather than an en dash.

  • Correct: "The average American spends between 2 and 4 hours watching TV every day."
  • Incorrect: "The average American spends between 2–4 hours watching TV every day."

Check Grammarly for more information on the en dash.

En Dash Shortcut

On a Mac, the keyboard shortcut for an en dash is 'option' + '-'

Additional resources: The Punctuation Guide's punctuation guide is a great go-to resource for any questions. DailyWritingTips wrote this humorous account of the ten most common hyphenation/dash errors.

6. Slashes

There are two types of slashes: the forward slash ( / ) and the backslash ( \ ). The backslash is reserved for computer coding. Spaces should never appear before or after forward slashes. 

  • "If/when you decide to show up, I'll be in the front row." vs. "If / when you decide to show up, I'll be in the front row."

Note: Forward slashes can be used to denote line breaks in songs, poems, and plays, in which case a space must follow the slash (e.g. "Moon above and waves below/ On the beach they lap ashore").

Ellipses

Both APA and Chicago assert that correctly punctuated ellipses have spaces between each point, as well as a space before and after the series of point. For example:

  •  "The room grew quiet . . . and the president entered." not "The room grew quiet...and the president entered." 

However, since "..." is so commonplace, you may choose to use either kind of ellipses (". . ." or "..."). The most important thing here is consistency.

 

More About Ellipses

  • Ellipses should always have three dots. A fourth dot indicates a period rather than a continuation of the ellipsis.  
  • In quotes, use three spaced ellipsis points "[ . . . ]" to indicate omitted material, unless that omission occurs between sentences, in which case there should be four points "[ . . . . ]" (an ellipsis and a period).

Countable vs. Uncountable Nouns

If an item can be counted (e.g. cats, bees, chocolate chips), it can be used with articles and quantifiers such as "a," "an," "some," "a few," and "many." These nouns can be both singular or countable. 

  • This is a cat. 
  • I ate a few chocolate chips.

Uncountable nouns come in a state or quality that cannot be counted (e.g. sand, liquids). Abstract nouns are also uncountable (e.g. creativity). These nouns are always considered singular and require singular verbs. They can be used with "some," "any," "a little," and "much."

  • This information is useless.
  • This information are useless.  
  • Have a little faith. 
  • Have a faith.

Some nouns can be countable or uncountable, depending on the context of the sentence (e.g. light, hair, time).

  • Countable: Did you have a good time at the festival?
  • Uncountable: I don't have time to do the dishes right now.

Note: Some nouns are both singular and plural (e.g. series, wood, deer). In these cases, the form of the verb depends on the context. 

  • This is my favorite type of fish. 
  • Fish are great pets!
  • I have six bonsai at home.

Note: If you're not sure how a plural noun should be spelled, check Merriam-Webster. Some nouns can be pluralized in different ways depending on the context (e.g. "fish" and "fishes").

7. Lists

There are many ways to structure a numbered or bulleted list. No matter which way you choose, lists should be clean, consistent, and in the style that is the most appropriate for the content (e.g. numbered lists for step-by-step instructions and bulleted lists for materials). Consistency and clarity are key (in addition to being grammatically correct!). For instance, you wouldn't want a list that has four items, but only one item has punctuation.

 

For more details, Grammar Girl has a great explanation. 

 

If the list is just a list:

You're likely to run into situations where the list is . . . simply a list. If that's the case, you'll want to aim for something that looks like this. It tends to look more aesthetically pleasing if you capitalize the first letter in this case.

 

My 5 Favorite Fruits

  • Mangoes
  • Strawberries
  • Cantaloupes
  • Pineapples
  • Apples

If it completes a sentence in multiple ways:

Think of this formatting as a "choose your own ending" list. In this case, the first letter of each bulleted point would be lowercase, as each bulleted point finishes the sentence. So, "You can refuse to celebrate" would be correct, while "You can Refuse to celebrate" would not be. These types of lists are punctuated as follows:

There are many ways to throw a party. You can:

  • refuse to celebrate!
  • invite your friends over.
  • take a vacation.

If the list is a series of sentences:

If the list is a series of complete sentences that follow a colon, try to punctuate it thusly. And the first letter here would be capitalized because each bullet point is its own sentence.

 

I'd like to tell you about my vacation today. Here's what I did:

  • I went to the store.
  • I pet some fish.
  • I explored some ruins.

If the list is composed of items and their definitions/explanations:

This is common in situations where both a short answer and a brief explanation are necessary. It often helps to bold the key term(s), though this is not a requirement. (Note that colons are preferred to dashes, here.)

 

There are three major types of blood vessels:

  • Arteries: These are the largest blood vessels. They carry blood away from the heart.
  • Veins: Veins are smaller than arteries and carry blood back to the heart.

Capillaries: These are the smallest blood vessels. They allow for the exchange of gases, nutrients, and waste between blood and the body's tissues.

If the list is a run-in part of the sentence:

Imagine if you were writing the sentence vertically instead of horizontally. The first letter of each item here would not be capitalized. If a list is a continuation of items in a sentence, try to punctuate it like what you see directly below. This sentence, if written horizontally, would look something like "As an editor, I like grammar, punctuation, and spelling." And none of those elements would be capitalized in that case, which is why you would refrain from capitalizing them in a list.

 

As an editor, I like:

  • grammar,
  • punctuation, and
  • spelling.

Semicolons for clarifying groupings:

Semicolons may be used to clarify groupings, especially when an item or multiple items in a list already have commas. Separate the items with semicolons:

 

Each chef took to a station and received:

  • a MIYABI knife, which is considered a work of culinary art;
  • a rolling mat, which is commonly used to prepare sushi; and
  • a slip, which contained the clientele's food order requests.

Make sure lists are parallel:

This means that all items in the list have the same structure (e.g. start with the same part of speech, use the same verb tense, use the same sentence type).

 

3 Reasons Summer Is the Best Season

  • It's warm and sunny every day.
  • The days are long.
  • cold drinks (nonparallel/incorrect)

How should you capitalize multi-word items in lists or tables? As long as you're consistent, you can use APA title case, sentence case, or all lower case. Generally, however, APA tends to look the cleanest.

What should you do if the list is long and each item is short? Long lists of short items create lots of excess white space on the page and should be converted to tables when possible.

8. Numbers

As a general rule, spell out numbers one through nine, and use numerics for numbers 10 and higher.

Multiple numbers in the same sentence: If you come across a sentence with numbers above and below nine, depending on the context, it may look best to spell them both out or use numerics for both. In essence, do what looks best/makes the most sense. For example, "six bananas and thirteen oranges" rather than "six bananas and 13 oranges" and "9 of the trail's 1,500 miles are passable solely at low tide" rather than "nine of the trail's 1,500 miles are passable solely at low tide." 

 

Exceptions:

Distinct categories and units of measurement: 

  • "It took four minutes to tally the 100 votes." rather than "It took 4 minutes to tally up the 100 votes."
  • "She completed the 26-mile run in under five hours and the 13-mile run in under two hours."

Two back-to-back numbers: 

  • "two 8-ounce cans" vs. "2 8-ounce cans"
  • "seven 3-pointers" vs. "7 3-pointers"
  • "five 20-story buildings" vs. "5 20-story buildings"

Medical Content (Human or Veterinary)

For drug dosages, strength, and frequency, stick to numerics for all quantities (e.g. "she was given 300 mg of echinacea every 12 hours; or "he was given 1 mg of the placebo every 6 hours").

Note: Exceptions to the above preferences include prose and autobiographical-style writing: "I was diagnosed with narcolepsy three years ago."

Units of Measure

When writing out numbers and units of measurement, always include a space between the two (e.g. 4 mg; 300 mcg; 5 mL).

 

Note: It is preferred to capitalize the "L" in milliliters as not to confuse it with an uppercase "i"; you may also consider first spelling out the unit of measure depending on the audience and the tone of the information being communicated.

 

Technical Content (e.g. measurements for DIY projects); use numerics.

  • "Use a 2-inch drill bit."
  • "Using your measuring tape, use the carpenter pencil to make a mark at 4 inches."

Distances

If the number is less than 10, it's up to your discretion whether to write it out. Consider what looks best to the reader. For example, the following sentences are both correct, but the numeric version looks far less clunky:

  • "San Francisco is a four-and-a-half-hour drive from Santa Barbara."
  • "San Francisco is a 4.5-hour drive from Santa Barbara."

Recipes

For sentences that contain multiple numbers, consider offsetting the instructions with written and numerical text. Make stylistic choices that will benefit the reader most. Make the instructions easily scannable. Considering the following examples:

  • "Line two 12-cup muffin tins with cupcake liners."
  • "Add 4 cups of icing sugar."
  • "Spoon the batter into the cups about three-quarters of the way full." OR "Carefully spoon the batter into the cupcake liners, filling them 3/4 full."
  • "Add the melted chocolate and beat it for 2 minutes."

9. Quotation Marks/Quotes

If a word or phrase has already been referenced once in quotes, it doesn't need to be quoted again (e.g. This tasty morsel, called a "cinnamon bun," should be eaten twice a day to keep the doctor away. Cinnamon buns are great for your health.)

 

Introducing Quotes

Generally, a comma is used to introduce quotes or dialogue, but this only works when the quote is syntactically dependent (i.e. stands apart from the surrounding text). For example: Louis barked, "How dare you touch my pink flamingos?"

  • Exception 1: If the quote is introduced by a conjunction like "that," "whether," or "if," we can skip the comma. Louis is always telling people that "flamingos make the best companions."
  • Exception 2: If the quote blends into the surrounding sentence, no comma is necessary. It wasn't long before he earned the moniker "Lawn Flamingo Louis."
  • Exception 3: If the quote is being introduced by a complete sentence (a.k.a. independent clause), you can use a colon. Louis always gives the same advice: "Get yourself some lawn flamingos, and you'll never be lonely again."
  • Exception 4: If a block quotation is being introduced by a complete sentence, you can use a period. 

Punctuating Quotes

In American English, periods and commas always go inside quotation marks.

  • I can never remember how to spell "sovereignty."
  • "You don't know who you're dealing with," she said with a smile.

Colons, semicolons, and dashes always go outside quotation marks:

  • Her favorite poem was "Where the Sidewalk Ends"; she spent days memorizing it.

Question marks and exclamation points go outside quotation marks UNLESS they belong with the quoted material:

  • Which character in Spongebob said, "Well, it may be stupid, but it's also dumb"?
  • Without missing a beat, he cried, "It was Patrick!" 

Additional Resources

10. Titles

  • Always italicize book titles, movie titles, etc.
  • Songs, article titles, and short pieces should be in quotation marks in titles and headings.
  • APA capitalizes all words four letters or more. That includes "with" and "from." Verbs, including "is," are capitalized.

Punctuation of Titles

Em dashes are too long in titles, and if possible, try to write the title without a colon (it sounds more conversational). Ampersands are usually avoided, though sometimes necessary in longer titles.

It's usually smart to refrain from using specific dates in titles (e.g. Top 10 Whatnots of 2011!), since they make that content less evergreen and would require regular updating, which can't be guaranteed.

 

Dates in Titles

When should you include a date in an article's title? They are probably necessary in articles that discuss products, events, releases, reveals, or reviews pertaining to a specific time frameday, year, decade, century, etc., for example:

  • "Best Video Games of 2018"
  • "The Top Country Albums From the '90s"

However, dates are probably not necessary in holiday gift-giving guides unless they are updated annually.

11. Headings and Captions

  • Headings: Bodies of text should be preceded by appropriate headings.
  • Captions: Photos should have captions, not headings. Add captions that make sense to readers and help them better navigate the article. Google also uses captions to explain images when readers are unable to see them (e.g. those that are visually impaired).
  • Movie titles and book titles: Always italicize book titles, movie titles, etc. 

Screen_Shot_2021-06-02_at_4.26.18_PM.png

12. Formatting

The Top of the Article (a.k.a. the "Welcome Mat")

The top of the article is incredibly important because this is where readers form their first impression of the article's quality and decide whether to continue reading or go back to the SERP (Search Engine Results Page).

 

Online readers are like potential buyers. When they land on an article, they're doing a drive-by of sorts, and if the article lacks "curb appeal," they're more likely to keep driving (or hit the back button) to find a more appealing answer. The title, dek, top photo, top heading, and first paragraph must be as good as they can be. Errors in these places might affect reader trust.

 

Important Fields

  • Dek: The dek appears under the title and before the body of the article. It most closely resembles a summary.
  • Meta Description: Meta descriptions are 160 characters or less and generally appear in Google SERPs but are not displayed on the landing page. A good meta description is the best way to grab readers' interest and can go a long way to improving the quality and quantity of your search traffic.
  • Teaser: A teaser is descriptive text that is used for promoting content. It appears as the description of an article when readers share it to social media channels (Facebook, Pinterest, etc.).

Numbering/Bulleting

Whenever possible, use the numbering/bulleting tool rather than manually entering numbers or bullet points. This is because the tool offsets the list and makes it much easier for the reader to follow.

 

Headings (H2)

Relevant, searchable headings are a good way to add shape to the page. If you have long blocks of text, consider breaking them up this way.

 

Bolding, Caps, or Italicization

Entire paragraphs should not be bolded, capitalized, or italicized. Use these options only to help the reader find what they're looking for or, in some cases, for stylistic effect.

 

Note: It is sometimes okay for entire sentences to be intermittently bolded, but do this very sparingly.

 

Necessary Italicization

Foreign words: Isolated words or phrases in a foreign language (not English) are to be italicized once if unfamiliar to the readers. If the word or phrase is repeated throughout the text, only italicize it on the first occurrence. If used infrequently, the italicization may be repeated.

  • If the word appears in Merriam-Webster, there is no need to italicize it (e.g. "froideur" and "gochujang" vs. "kaki-gori").

Latin names: The Latin names of species of plants and animals are italicized. Binomial names consist of the capitalized genus (generic name) and the lowercase species name (specific name). For example: "the green sea turtle or Chelonia mydas."

  • Binomial names in titles and headings: It is acceptable to keep the species name in lowercase within a title or heading. For example, "Temperature-Dependent Nest Ratios in Chelonia mydas Populations"

Ships and other named vessels: Names of specific ships and other vessels should be capitalized and italicized. BUT, any abbreviations that precede the name should not be italicized (e.g. USS or HMS).

  • the USS Constitution
  • the space shuttle Enterprise
  • the Beagle

Movies, books, sculptures, etc.: Always italicize book titles, movie titles, etc. (Note: Songs, article titles, episode titles, and short pieces should always be in quotation marks. For example, "Threat Level Midnight" is one of my favorite episodes of The Office.) Although video game titles should be italicized (for example, The Legend of Zelda), the names of apps and other software should not (for example, Snapchat).

When to Use Italics vs. Quotes

Italics

Quotes

book titles

book chapters

movie titles

article titles

TV series

TV episodes

album titles

song titles

newspapers, journals, and magazines

poems

titles of comic-book series or strips

(for multi-volume series, the formatting is as follows: "The Flash vol. 3")

comic-book issues, chapters, and episodes, and individual editorial cartoons or panels

13. Videos

Add a video if an article can benefit from it (e.g. a video can round out a short article). They can be embedded for direct integration as a simple embed (Instagram, Twitter, YouTube) or uploaded in the media library (see How to Embed Content in Tempest). It's recommended to do a search around your main topic to see if the SERP has videos. If so, you know that readers want to see videos around your topic and you should probably include one!

 

Tips for Selecting a Video

  • Make sure it's high quality.
  • Watch the video's content and scan long videos to make sure it doesn't violate Adsense policies or contain offensive dialogue, etc.

14. Pull Quotes and Block Quotes

These are a great way to add visual interest to a page (e.g. cute/catchy/chatty asides, interesting bits or quotes). However, they should be used with discretion. 

 

Pull Quotes

A pull quote is a quotation from the existing article; it emphasizes an important point within the text. This feature:

  • is considered a louder treatment than a block quote.
  • is not seen as "included" in an article by Google, bots, etc. (i.e. is not considered duplicate content).
  • will appear in large font in the site's primary color palette or a customized color.

Block Quotes

A block quote (block quotation) is a large quotation that features text from another source that is not included in the article (e.g. book, website). This feature:

  • is stylistically subtle.
  • appears in-line as part of the content.
  • is of a color taken from the site's primary palette.

15. Tables

  • You can add tables to an article that has long lists of short items that create long columns of white space on the page.
  • Tables make quick comparisons much easier, so they work very well in reviews of several products, for example. They are often ideal in articles that compare two or more things.
  • Instead of downloading or cutting/pasting a table from another publication to use in an article, it's always better to create your own table. Unless you can verify with complete certainty that the table is in the CC for commercial use, you should treat tables as you would any copyrighted photo or image.

16. Sneak Peeks (SPs)

Adding a Sneak Peek to the top of a longer article helps to give readers a heads-up about what answers they will find. Numbered or bulleted lists of content also help information convert to featured snippets, so they're a good thing to add if necessary and possible (e.g. on reviews of many items or long articles that span multiple topics). Try not to have any preamble, intro, or words between the heading and the list. This will make it easier to convert to a featured snippet.

 

Note: Short articles and articles with a structure that's already strong probably don't need a Sneak Peek.

17. Images

Adding Original Images

Original images are always preferred in an article, as they boost author expertise in the eyes of the reader. For example, DIY projects benefit greatly from the inclusion of original, step-by-step images. 

 

Image Size

To appear as full-width on Phoenix, images should be at least 700 px wide. 

 

Galleries

Tempest has two gallery types: content galleries and photo galleries.

  • Content Gallery: The content gallery feature is reserved for images that are paired with long-form text. This format is frequently used to show photos in a sequence (e.g. a series of photos with multiple steps). This feature takes up the full width of the column and is meant to easily engage users.
  • Photo Gallery: The photo gallery showcases images by offering a full-screen experience. This feature displays in-line in the body of the article and must be opened by the user for engagement. 

Note: If the majority of the photos in any given gallery are practically identical, you should pare it down so that only a few eye-catching ones remain. 

Adding CC Images

If you do not have original photos, add relevant and useful CC images. All added images should be properly sourced. Remember that images should do two things: convey important information and set a mood/appeal visually. Here are a few good CC sites you might use:

  • Flickr: Flickr has a wide range of photos of varying quality. Keep in mind that not everything on Flickr is CC. You'll need to select "all licenses" and select "commercial use" (or "commercial use and mods allowed" if you plan to add text or modify the image in any other way).
  • Wikimedia Commons: This site exclusively features CC and/or public domain images.
  • Pixabay

Note: Avoid adding blurry, pixelated, small, duplicate, or near-duplicate images.

Adding Text to Images

For authors with active Pinterest audiences, images with text overlay may help drive clicks. Sites such as AdobeSpark, Canva, and Fotor can be used to add text overlay to images. These sites are all more or less the same, so use whichever works best for you. Take extra care not to add images with grammatical errors in the overlaid text.

 

Note: Keep in mind that while small text overlay may look great on desktop, it will likely be very hard to read on mobile, where most traffic comes from! Be sure to check the mobile preview to make sure your text overlay is readable in both formats.

Image Metadata

  • Captions: As a general rule, images should have captions. Google looks at captions for information about an image so that it can translate well on Google Images. Google also uses captions to explain images when readers are unable to see them (e.g. those that are visually impaired). Make sure your captions are engaging, specific, descriptive, and help readers interpret the image.
  • Captions are usually written in sentence case with terminal punctuation. Sometimes, the caption is written in APA title case and does not contain terminal punctuation. Again, it should be consistent within the article.
  • If the caption is a sentence fragment (e.g. 1982 Mercury Capri With a Broken Sunroof), you don't need to use terminal punctuation.
  • If the caption is a sentence fragment with internal punctuation, convert it to a full sentence or rework it to remove internal punctuation (e.g. "Chocolate, sprinkles, and bananas on top" should be "Here's a sundae with chocolate, sprinkles, and bananas on top.")

Note: Since you can't italicize in captions, all book titles, movie titles, etc. should be in quotation marks.

  • Title: The image's filename or title should accurately describe an image in order to be relevant in search rankings. Titles are not modifiable once the image is uploaded. Rather than "file_3" choose something accurate and descriptive, such as "decorative-fruit-platter."
  • Alt Text: Alt attribution describes the contents of an image to search engines (to return an appropriate image for the query) and aids those with visual impairment or those using screen readers to interpret images on the page via the descriptions. Alt text should be at or below 150 characters in length. (Note: Alt text is not visible on the article.)
  • 
Attribution: Provide a source name and URL to properly attribute images. Once the attribution is set, it is automatically ported whenever the image is embedded.

18. Headings

  • Headings tell the readers what answer they will find in the following text, so they should be as descriptive and engaging as possible.
  • Headings should be in APA title case. 
    • In some cases, headings may be a punctuated sentence, in which case either APA title case or sentence case are acceptable (e.g. "How Do I Apply for a Salvaged Title?" or "How do I apply for a salvaged title?"). Overall, an article's punctuation and capitalization of headings should be consistent.

Organization: How to Organize an Article

Inverted Pyramid

Information should be presented in an inverted pyramid. This means that the answer should be presented at the top of the article, and the text should be arranged from most to least relevant. Avoid portions of text that repeat, distract from, or don't add to the main topic and might affect reader trust.

Anecdotal or tangential details that contribute to (rather than hurt) reader trust might be appropriate if it is a personal story and serves the purpose and topic of the article, but it is sometimes prudent to move this content closer to the end of the article (e.g. in a DIY article, the reader is interested in learning how to complete the project, so any anecdotal information is best located after the how-to section).

 

What is the inverted pyramid?

The inverted pyramid is a way of organizing and prioritizing text in an article. This is especially important for online content, as readers have a high likelihood of clicking away if their query is not answered immediately. The inverted pyramid doesn't build to a climax (as traditional writing does). Instead, a quick, elegant, and concise answer should be given right at the top and then followed by an explanation.

19. SEO and User Optimization

Instead of organizing your article based on SEO, prioritize reader happiness (user optimization) by creating logical sections with headings. Online readers read in F-shaped patterns and skim to find what they're looking for. Specific, helpful, conversational headings make it easy for readers to find the answers they're looking for.

 

User Optimization and the Hierarchy of Different Headings

  • H1: This is reserved for the title, contains important keywords, and describes the content of the article. It tells readers what to expect when clicking on your article. Keep in mind that even if your H1 is strong, readers will return to the SERP if your query isn't answered immediately, which tells Google that your content isn't great.
  • H2: These are used for headings and have less weight than H1 but more weight than H3. H2s offer bite-sized pieces of information and make the content easy to digest and scan. They guide the reader toward the answers they are looking for. Make headings as conversational and clear as possible, and avoid single words or general fragments (e.g. "How to Fix a Zipper" or "How to Calculate Your Dog's Nutritional Requirements").
  • H3: This is the least powerful heading in terms of SEO, but it can be important for user optimization. Often, nesting these below an H2 heading can create an easily skimmable, organized article. H3s also add visual interest to an article and break up long blocks of text. 

Tip: Having an H2 or H3 question with the answer right below may give the article a better chance of showing up in a featured snippet. Headings like "Introduction" and "Conclusion" serve no purpose and should be avoided.

What is a featured snippet?

Featured snippets (sometimes called the answer box or position #0) provide the quickest, most concise answer to a given query right at the top of the SERP (Search Engine Results Page). They come in various forms depending on the answer (i.e. paragraph form for definition-type content, bullets or numbers for lists or how-to instructions, tables for comparisons or data, and even YouTube videos). 

 

If your article has the featured snippet (FS) for a given query, your search traffic will increase (especially if your article also owns the first search result). Research the main query of your article in Google, see what kind of featured snippet is shown (if one is shown at all), and optimize for this type of snippet (i.e. if it's a table, create a table answering the query in your article as well). 

Pro Tip

Whenever possible, it's smart to give the reader the answer to their search query as quickly and succinctly. The answer should appear as close to the top heading (query) as possible.

Scannability

Formatting information with bullets, block quotes, pull quotes, numbering, tables, etc. helps readers scan to find the answers they're looking for. Other elements that boost scannability include headings, bold text, graphics, captions, and Sneak Peeks (SPs). (This is a time to put on your "reader hat" and think about what elements would best help you navigate the page.)

 

Rich Vocabulary (or Word Choice)

When writing an article, it's a good idea to use a variety of words to describe things rather than repeat the same words (which can lead to stuffing). Apt synonyms and expert terminology will enrich understanding and enliven the writing. For example, if you're writing an article about split little toenails and do a Google search, you'll come across the term "accessory nail of the fifth toenail" in Wikipedia; adding this term to the article is an excellent idea.

20. Crafting Titles (H1)

The title (H1) is the most important sentence in the entire article and the one with the most eyes on it. It is weighted most heavily by both readers and search engines. Titles must be an accurate representation of the content and should contain words that people are searching for online. Take extra time and care to ensure that your title is clear, direct, and as conversational as possible.

  • Titles should be both conversational and enticing (e.g. "How to Plant Bulbs for a Pop of Spring Color" is much more engaging than "Spring Bulb Planting").
  • A title should not truncate on a SERP. Use the MOZ title tool to make sure it doesn't. (Generally, you should keep titles about 60 characters long.)
  • Avoid em dashes since they take up too much horizontal space.
  • APA capitalizes all words four letters or more. That includes "with" and "from." Verbs, including "is," are capitalized.
  • Songs, article titles, and short pieces should be in quotation marks.
  • Ampersands are usually avoided in titles, especially for academic subjects.
  • If possible, try to write the title without a colon (it sounds more conversational).
  • It's usually smart to remove specific dates from titles (e.g. Top 10 Whatnots of 2011!), since they make that content less evergreen and would require regular updating, which can't be guaranteed.

21. Links

Open-Faced or Bare URLs

Open-faced (or bare) links, such as https://www.dmv.ca.gov/portal/dmv, are not allowed within the body of the article and are not allowed to be hyperlinked or used for citations. Instead, use anchor text, such as "visit the California DMV" (see next section). An exception to this might be citing sources.

 

What is anchor text? Anchor text is descriptive text that is hyperlinked, informs the reader of what they are clicking on, and opens to the target web page.

Unhelpful Links

Any link included in an article should:

  • be helpful to the reader,
  • include additional information,
  • have specific anchor text, and 
  • be relevant to the information.

For example, a link to a Wikipedia page may or may not be necessary depending on the content. A generic redirect to "sunflower" on Wikipedia is unnecessary, whereas a redirect to "Hashimoto's disease," an uncommon condition, may be helpful.

 

Acceptable Links

External links should be used sparingly, as each one is an invitation for the reader to go elsewhere. Reserve hyperlinking for only the most relevant, trustworthy, and necessary links. The heavy use of links may be acceptable for craft and DIY projects when the project concept and project examples referred to in an article are hosted on another site. 

 

Anchor Text

Anchor text should be as specific as possible and aim to let the reader know exactly where they're going. Here are some examples of good versus bad or unacceptable anchor text.

22. Citations

In lists of sources, use APA citation format. You may choose to use this app that helps you format properly. Sources that are frequently cited include journal articles (print or online), websites, magazines (print or online), and books (edited, e-books, and chapters). Some things to keep in mind:

  • Include the retrieved date for websites (when available).
  • Hyperlink the title rather than the URL.

23. Spammy Elements

"Spammy elements" are products, links, and wording (including keyword stuffing) that feel excessive and make the article as a whole appear to be motivated by earnings rather than motivated by a desire to share information. What is classified as spammy?

  • Promotional links. These include:
    • Links that promote something rather than help the reader better understand the content of the article.
    • Links that have an ulterior motive (monetary or otherwise).
  • Self-referential, redundant, or poor-quality links.
  • Unnecessary or unused products (products should be useful to the reader and something they would expect or be pleased to find).

What is keyword stuffing and what should I do about it?

Keyword stuffing is a technique where important search terms are repeated excessively in an attempt to gain a rank advantage in search. Keyword stuffing can be annoying, redundant, spammy-feeling, and trust-reducing for the reader. Keyword stuffing of "German Shepherd":

German Shepherds are one of the most popular dog breeds in North America. Why? The German Shepherd is known for its trainability and intelligence; the breed has also served the public for ages. It's widely known that German Shepherds assist police officers, search and rescue volunteers, and military personnel. Are you thinking about making your next dog a German Shepherd?

 

How do I know if an article is stuffed?

  • CMND+F: If you're wondering if an article is keyword stuffed, hit cmnd+f, enter your keyword(s), and see how your article lights up.

Read It Aloud: When you read the article out loud, does it sound unnatural? If it sounds off, it's probably stuffed.

Screen_Shot_2021-06-02_at_4.34.54_PM.png

24. Reader-Trust-Affecting Errors

Overarching Errors:

  • lack of overall knowledge of the topic
  • excessive linking (especially unhelpful, spammy, redundant, self-promotional, or untrustworthy links)
  • poor visual appearance (e.g. stock images, low-quality images, etc.)

Poor Grammar, Punctuation, Syntax, and/or Typos:

  • misspellings
  • words that are missing or duplicated (e.g. "The cat cat sat in my lap" or "The dog barked the child")
  • punctuation that convolutes the meaning of a sentence or is missing at the end of a sentence
  • errors that make it necessary to re-read a sentence multiple times in order to understand what the author is trying to say
  • run-on sentences, incomplete sentences, or comma splices
  • subject-verb disagreements (e.g. The banks stores money)
  • changing tense mid-sentence or using tense inappropriately
  • lack of parallel structure (e.g. I walked the dog, the cat, and fed the bird)
  • not capitalizing proper nouns or incorrectly capitalizing words; sentences that don't begin with a capital letter

Note: Errors in prominent locations (e.g. the Welcome Mat) are more likely to affect reader trust.

25. Additional Helpful Resources

  • American Psychological Association: The APA style guide is based on American psychology standards. If you'd like more information, you can visit their website, or if you need formatting help, Purdue's OWL has a formatting and style section devoted to this guide.
  • Chicago Manual of Style: Chicago Manual of Style (better known as CMS) is the go-to guide for most book publishers. CMS does not make their book available online; however, they do have a "but what about this instance that isn't in the printed guide" section.
  • Grammar Girl: Grammar Girl is incredibly helpful, very accessible, and a bit quirky. Her blog offers a great guide to anyone looking for answers to grammar-related questions.
  • Grammarly: Grammarly's Word Blog is a great resource for any grammar-related questions that you might have. They present their information in succinct, straightforward, easy-to-read articles.
  • Purdue OWL: One of the more academically minded resources you're going to find, Purdue's Online Writing Lab is an invaluable resource for all of your editing and grammar needs.
  • Capitalize My Title: This is a quick way to be sure that your title is capitalized according to APA guidelines (though you may need to double-check the capitalization of important words and two- and three-letter verbs).
  • MOZ Title Tool: This is an excellent site for estimating the length of an article's title tag.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk