V² > Plan > Flow > Publishing > Style Guide

[VillageHubertChen]

Tasks

• HC: Create Issue
• HC: Add Link to Article in Reference of this Issue
• HC: Classify Labels, Milestone & Assignee
• HC: Create Article
• HC: Create Title / Subtitle / Abstract
• HC: Enter Issue No in Article
• HC: Find reference style guide and link to Article
• HC, TC: Hand over meeting on writing style guide
• TC: Write style guide
• TC: Trigger review to HC
• TC: Include review feedback

Reference

• V² > Plan > Flow > Writing Articles > Style Guide

[tcaswelch]

V² Written Style Guide

(rev. 1.0)

I. Goals
II. Grammar, Punctuation, & Capitalization
III. Style & Tone
IV. Other: Attribution & Social Media

Goals

• Inform (educate) the user.
• Write clearly, using words the audience understands.
• Compose simple, active voice sentences.
• Understand the audience and speak directly to the reader.
• Use active voice, appropriate grammatical person, present tense, and the imperative mood.
• Determine if the text requires a change in grammatical person or past tense, future tense, and/or declarative mood.
• Avoid unnecessary repetition, redundant jargon, and passive voice.
• Evaluate your writing: write, review, and repeat.

II. Grammar, Punctuation, & Capitalization

Acronyms: Don’t assume your audience knows what you’re abbreviating. Spell out acronym titles on first reference and follow with the acronym in parenthesis. Every proceeding reference can be abbreviated. Example: The Internet Marketing Association (IMA) is one of the fastest-growing internet marketing groups in the world.

Ampersand: Avoid unless part of a proper name, tagline, title, or subheading.

Apostrophe: For plural nouns that don’t end in an “s,” add an apostrophe s to the end of the word. For nouns that end in an “s,” add only an apostrophe. Example: several businesses’ websites

Avoid using apostrophes in plurals. Example: URLs, iPhones, FAQs

Commas: Observe the Oxford comma. In series of three items or more, keep the comma before and/or. Example: We’ve got to eat these apples, bananas, and oranges. (Not “We’ve got to eat these apples, bananas and oranges.”)

Company and product names: Follow an organization’s conventions as to how it capitalizes and punctuates its name, paying special attention to capital letters in the middle of the name and punctuation. Example: eBay, HubSpot, YouTube

Ellipses: Use sparingly within copy.

Em dash: Use to set apart entire phrases from the main body of a sentence, and do not separate the dash from the words that precede and follow it. Example: If you want to know—and surely you do—then you must ask.

Lists:

• Always capitalize the first word of each bullet point. Just as in regular text, it is important to punctuate lists correctly.
• If the list is made up of phrases, capitalize the first word of each list item. Do not end each list item with a comma or full-stop (period).
• When items are complete sentences, begin with a capital and end with a period.
• List items are sometimes an initial phrase followed by a complete sentence. In that case, use capital letters and full stops (periods) for the phrases as well as the complete sentences.

Keep your lists simple.

Examples:
I love fruit, including:

• Apples
• Oranges
• Bananas

Here’s how you can find the best fruit:

• Go to the grocery store.
• Find the produce section.
• Search for the fruit that’s in season.
• Make sure each piece of fruit you pick out looks delicious.
• Buy the fruit.
• Take the fruit home with you.

Intel: Always capitalized.

intel.com: Always lowercase (within a sentence or on its own), unless you’re using it to start a sentence. Example: Intel.com is a great resource. You can find the answer to your question at intel.com.

Numbers: Spell out cardinal numbers one through nine, and use numerals for numbers 10 and above. When a number begins a sentence, spell it out. Express large numbers in numerals followed by million, billion, and so forth. If expressing a number greater than 999 in numerals, use a comma. In titles, use numerals. Example: She has nine cats, but he would like 90. One hundred would be too many. So would 5,000. One billion is out of the question.

OK: Not o.k. or okay.

Percentages: Always use the % symbol when reporting statistics. Avoid starting a sentence with a percentage. Example: Did you know 98% of statistics are made up?

Periods: One space after periods and at the end of sentences.

Pronouns referring to companies: When referring to a company, use the third-person singular pronouns it and its. A company is treated as a collective noun and requires a singular verb and a singular pronoun.

Subheadings: When using a subheading, capitalize the first letter of every word (like with titles) unless it's in sentence form—then use sentence capitalization and punctuation. If you’re using title capitalization, use an ampersand in place of the word “and.” If you’re using sentence capitalization, spell out “and” as usual.
Examples:

• Don’t be outsmarted.
• Do you have enough apples and oranges?
• How To Make The Most Of Your Time
• Exports & Imports
• April, May, & June

Time: Use cardinal numbers and a.m. and p.m. to indicate time. Use “noon” to indicate 12 p.m. Example: I was awake at 12 a.m. and 4 a.m., but I fell asleep at my desk at noon.

Titles: Capitalize the first letter of every word in titles, and always use an ampersand in place of the word “and.”
Examples:

• 4 Ways To Make Writing For The Web Less Complicated
• What Is Inbound Marketing & Why Should I Care?

Commonly Used Words/Acronyms:

• all-in-one computer (AiO)
• blog/blog post (The articles we write are called blog posts, not blogs.)
• call-to-action (plural: calls-to-action, abbreviation: CTA or CTAs)
• cell phone
• ebook (“Ebook” when used in a title/headline; avoid using at the beginning of a sentence)
• email/email address (We don’t ask for someone’s email—we ask for their email address.)
• Facebook
• homepage
• internet
• LinkedIn
• tweet
• Twitter
• URL
• website
• white paper

III. Style & Tone

Style

We want our audience to know a V² article or story when they read it. Here are some key components of our copy:

• Use first person, active voice. Use first-person references like “us,” “we,” and “our team.”
• Keep it conversational, yet polished. Be polite in your writing, but don’t be afraid to make bold statements.
• Make articles scannable. We include all of the following in our copy:
  • Short paragraphs
  • Lists
  • Headings
  • Bold and italic
  • Blockquotes
• Parentheticals: We love using them, but limit them to one per paragraph.
• Keep it simple. The fewer words it takes you to accurately describe something, the better.

Tone


We want our content to have personality. It shouldn’t ever be boring or stagnant. At V², we’re awesome, fun people! And our writing should reflect this. So, enjoy yourself! Keep things informative, but don’t be afraid to be light-hearted. (After all, who wants to read something stuffy?) 

Content must be relatable to readers. Therefore, casual, conversational, easy-to-understand copy is a must. We want to consider our audience each time we write to make sure we aren’t using industry-specific jargon they may not understand. 



IV. Other: Attribution & Social Media

Attribution: Always, always give credit to another person’s idea (in whole or in part). Link to the original source, if possible. When referencing online articles in your work, always add a link to the source website spanning a phrase that you’ve written. If you use the title of the article, no italics or quotation marks are necessary. Never cite an article using the word “source.” Make sure all external links open in a new browser tab. Internal links should open within the same browser window.

Social media: We’ll play by the “rules” in this style guide on social media, too. Keep your posts respectful, polished, and conversational, and always edit for content and grammar. Social media moves fast, but how we represent our brand and our clients will stick around for a long time. On Twitter, use your best judgment to fit the character count; for example, symbols instead of spelled-out words are OK.

Special thanks to Wikipedia, HubSpot, and Buffer for providing excellent style guide templates (here, here, and here), which we adapted and used in part in creating our style guide.

[VillageHubertChen]

Questions to Author / Change Lists

@tcaswelch

Questions / Tasks

• I do not understand the sentence: "Determine if the text requires a change in grammatical person or past tense, future tense, and/or declarative mood." Can you rewrite it?
• I rewrite Title / Subtitle and abstract in what I believe is congruent with your style guide. Please check it and give me feedback.

Change List

[tcaswelch]

Excised the "Determine if..." entry. Good call: it really made no sense in context.
I'm still feeling my way into the Markdown flow; should I push the rest of the text to the article and then attack formatting adjustments there, or should I proceed via pull request?

[VillageHubertChen]

Hi Tom,

Your comment is confusing. Have you made changes and not pushed yet? If so, then they would be lost if I continue making changes and if you finally push them you would overwrite my changes. Please contact me before I continue. I also would like to know if I am in the right direction here before continuing writing.

As for pull request I have not figured that one out yet.