Open Source Comms Style Guide

Stay organized with collections Save and categorize content based on your preferences.

This style guide is short and to the point. It is designed to help you look good and save time in editorial so that we can publish your post sooner than later!

A few tips:

  • Posts should be short, to the point, and informative.
  • Blog posts should be between 500-1,000 words.
  • Write for a general technical audience and include links to external sites that contain additional details.
  • We encourage including at least one image (250x250 pixels minimum), but understand that not all projects have logos or graphics available. See Moonbase and these icons for potential use in your post.

Quick reference

We follow Associated Press (AP) style and the Google Developer Documentation Style Guide with some exceptions. Here are a few rules:

  • Open source: Don’t capitalize or hyphenate open source unless it’s part of a proper noun (like Google Open Source).
  • Communities, not community: it's tempting to refer to "the open source community," but open source is not a monolith. Unless you're referring to a specific community, please use the plural form of the word.
  • Post title: only capitalize the first word and proper nouns in your post title.
  • Oxford comma: we encourage the use of serial commas, in line with the technical documentation style guide.
  • Small numbers: spell out numbers less than 10, except for measured quantities like “2TB hard drive.”
  • Media titles: italicize the titles of newspapers, books, magazines, movies and TV shows.
  • Double spaces: use a single space after periods and other end marks.
  • Dashes: use an em dash (—), not a hyphen (-), to set off distinct thoughts within a sentence. On a PC use ALT + SHIFT + - and on a Mac use OPTION + SHIFT + -
  • URL: Please do not use markdown when submitting copy; hyperlink your URLs to a relevant word or phrase.
  • Exclamation points: use sparingly!

Voice

The Google voice is friendly, conversational, straightforward, clear, helpful and, when appropriate, playful.

Posts should be short, to the point and informative. They can be technical in nature, but frequently link to external websites that contain additional details as the skill level and subject matter expertise of our readers vary widely. Posts with technical details tend to perform better.

Images and video

Every post should include at least one image, whether that’s a logo, photo, chart or diagram. The first image in a post will be used as its thumbnail on social media, so make it good!

If you want to include a video, it needs to be hosted on YouTube.

Byline

Blog posts are signed “Name, Team.” We generally don’t list roles or titles, and while we prefer to have only one author in the byline, we may allow two authors in exceptional circumstances. Some examples:

  • Stephanie Texas, Google Open Source
  • Brian Freedom, Chicago Engineering Team
  • Josh Serious, Site Reliability Engineering Team

Additional resources

You can find more guidance here:

  • Social Toolkit 2.0 provides guidance for Google communications in general.
    • Voice and Style offers guiding principles to help you find the right voice.
    • Style Guide covers style, grammar, and punctuation.
    • Glossary covers common words and phrases that tend to confuse people.
  • Google Developer Documentation Style Guide provides guidance for documentation, which is useful for all developer-facing communications.