Grammar and usage

This guide will help you use words and transitions consistently as you create content for GitHub audiences. You’ll find a list of particularly tricky words at the bottom. Any rules mentioned in this guide override external sources.

Grammar and usage

Look to the Microsoft Style Guide or the Chicago Manual for anything not covered here. For guidelines on accessible writing as defined by the Americans with Disabilities Act, please refer to ada.gov.

Acronyms

When introducing an acronym, always spell out the first full mention in body text and specify the acronym in parentheses. Then use the acronym for all subsequent mentions. Use either the acronym or full version in titles.

Example: Git is a version control system (VCS). Teams use VCSs to see how files change over time.

If your audience is familiar with an acronym, you can use it without spelling it out.

Use: API, CSS, HTML, npm, VR, VPN, CI/CD

Abbreviations

Only use abbreviations with a period if there’s limited space for copy—in a tweet or push notification for example.

Example: Universe speaker proposals are due Sat., July 24. Example: We’ll cover Git tips and tricks, applying open source best practices to proprietary software, etc.

If your audience is familiar with an abbreviation, go ahead and use it.

Use: apps, wifi, macOS

Ampersands

Don’t use ampersands unless you’re referencing a brand name, for example: Proctor & Gamble.

Buttons

When instructing someone to use a button, use “click” (without “here”) unless you’re writing for a mobile app experience—then use “tap”.

Avoid: Press the button, hit the button

Use: Click the “Projects” tab, tap the “Projects” tab

Calls to actions

Be specific about the action you’re encouraging. Keep it short, and use common words. Avoid overly technical terms, slang, or region-specific vocabulary. And try not to use adjectives like “free”. Never use “here” or “click here” in call to action. Never use punctuation in calls to action.

Also, primary actions should be easy to find. Separate them from a body of text with a paragraph break.

Avoid: Terminate session, click here, complete registration for a free account

Use: Exit, see documentation, get started

Capitalization (products)

Always capitalize products that are owned or created by GitHub and include “GitHub” when you mention them for the first time. You can use the capitalized product name without “GitHub” for subsequent mentions if they’re not starting a sentence. Don’t capitalize commonly-used GitHub features, like “topics” or “issues”.

Capitalize “Blog” and “Changelog” when referring to the GitHub Blog or the GitHub Changelog. Don’t capitalize them when referring to generic “blog” or “changelog” posts.

Example: Customize your workflow with GitHub Marketplace. Find the right tools for your workflow in Marketplace.

Example: Subscribe to the GitHub Blog for updates.

Example: Check out our blog to learn more.

Use: pull requests, topics, GitHub Enterprise Cloud, Electron

Properly capitalize languages and other companies’ products. Begin Apple devices like “iPhone” with a lowercase letter, even when they begin a sentence.

Use: Linux, iPhone, macOS, Python, Windows 10 OS

Cases (capitalization in titles and UI)

Headers and UI elements

  • Titles, headlines, and buttons: Use sentence case for all headlines, titles, and buttons.
  • Subject lines: Use sentence case for all subject lines, unless there’s a single lowercase word.
  • Forms: Use sentence case for form titles and form fields.
  • CamelCase: Avoid CamelCase, except in the case of GitHub of course.

Titles and teams

  • Business titles: Capitalize formal business titles. Downcase titles when referring to them in general, like “software engineers at GitHub”.
  • Team names: Capitalize “Team”. For example: Services Team, Design Team, Data Science Team

Commas

We always use the Oxford comma. Refer to the Chicago Manual for comma guidelines.

Contractions

Contractions can give writing a warmer, more conversational feel. Always opt for one unless it introduces confusion or weakens meaning. If you’re writing words that will be translated, avoid ambiguous contractions and contractions using “is”, “would”, “have”, “are”, “were”, and “did”.

Avoid: We’d, who’d, they’d, they’re, he’s, could’ve, should’ve

Customers and users

Try to avoid describing our community as “customers” or “users”. Try to get more specific. Instead, use “people”, “developers”, “team members”, “community”,  or the group’s functional role, for example: “contributors” or “maintainers”.

Dashes

Use em dashes sparingly, and remember, not all mediums (like email subject lines) display em dashes.

Example: Our Student Developer Pack comes with unlimited repositories—perfect for all of those summer projects.

Use a hyphen without spaces on either side for time spans and linked words.

Example: The GitHub Services Team offers classes Monday-Friday.

Example: Join us between 11 am-1 pm.

Example: GitHub Universe is a three-day conference.

Dates

Include and spell out the month in dates. Only include and spell out the day of the week if it’s helpful to your audience. Only abbreviate if space is limited. Do not use the “nth” format when referring to specific days.

Example: Join us for GitHub Universe on October 12.

Example: Speaker proposals are due on Friday, July 28.

Avoid: September 2nd, May 4th

Ellipses

Don’t use ellipses unless you’re omitting words from a quote.

Emoji

Emoji can be expressive and add visual interest, but use them sparingly and only when they add value to short-form writing. Never use emoji to replace words. Consider screen readers by using emoji with short and descriptive names like :heart: or :smile:.

Emphasis

Use titles for emphasis, and use bold or italic as little as possible. Use bold when referring to UI elements. Use italics when introducing a new word or concept in educational writing or when referring to filenames. Do not italicize new features.

Example: Use “for example” either after the example or with the example following a colon or in quotation marks. Avoid “e.g.” or “i.e.” to make writing friendlier for non-native English speakers.

Exclamation points

Use exclamation points sparingly. Too many can feel disingenuous and overwhelming.

File names, types, and extensions

Write file names in lowercase unless the file is usually capitalized and italicize them. Write file types in all caps unless the file type is not abbreviated.

Example:setup.exe, README.md, CONTRIBUTING.md

Example: PDF, JPEG, Markdown

Folders

When referring to folders in a repository, use a code block with backticks.

Example: Add an issue template to the .github folder.

GitHub

Always use correct capitalization when referring to “GitHub” or “Git”. Never use “GitHub” as a verb. You don’t have to capitalize “Git” when it’s part of a command, like “git checkout” or “git merge

Hashtags

Use hashtags sparingly and in a way that’s appropriate for the distribution channel you’re writing for. Use them when they’re established for specific campaigns and events, but not for discovery, tagging, or cheekiness.

Lists

Use numbered lists if sequence is important, like in instructional steps or top 10 lists. Use bulleted lists if sequence isn’t important. Make sure all of your bullets are in the same tense, and try to keep a consistent character length for list items. Introduce the list with a sentence ending in a colon or in a sentence fragment.

Capitalize the first letter of each list item. If one or more list items contain a complete sentence, use a period after each list item, even if some aren’t complete sentences. If no list items contain a complete sentence, don’t use punctuation in the list.

Example:

Your GitHub Developer Program membership includes:

  • Developer product news delivered to your inbox
  • First access to hackathons
  • Priority access to GitHub conference ticket discounts
  • GitHub.com credits
  • Discounts to cloud application hosting services

Master

Avoid “master” when referring to the original branch or database. Use “main branch” or “primary database” unless context calls for another alternative.

Numbers

Write out “one” and every number less than 10. Use numerals for numbers greater than nine, like 10 or 42,093.

Follow this rule for bigger numbers, and write out “hundred”, “thousand”, “million”, and “billion” when they’re in body text, for example: “There are nine billion pull requests and 27 million developers on GitHub.” Big numbers can be abbreviated in titles and when there are space constraints, for example: “27M developers”.

For numbers larger than 999, use a comma every third integer. For example: write 1,200,000 instead of 1200000.

When abbreviation is necessary, use the # symbol rather than “no”.

Example: There are 22 million developers in the GitHub Community.

Page names and UI references

When referring to unclickable page names and sections, write them as they appear in the interface in quotation marks. When referring to button or link text that a user should click on, use bold text without quotation marks. Make sure all UI references match the capitalization in the interface.

Example: Go to the “Marketplace Purchases” section, and click Edit to upgrade your app.

Periods

Please use only one space after periods.

People and communities

Make sure you’re accurate and empathetic when referring to individuals and communities. When in doubt, ask how they’d like to be described and don’t make assumptions. If you’re referring to people within the GitHub community, use “people” or a more specific functional role rather than “users” or “customers”. Use “they” as a singular pronoun if you haven’t confirmed a subject’s preferred pronouns. Never include age, gender, race, disabilities, or other personal characteristics unless they’re relevant to the content and you’ve confirmed you have accurate information.

Note: Avoid gendered language. For example: Use “businessperson” instead of “businessman”.

Note: If you’re referring to a person or people who identify as Black, always capitalize “Black”. If you’re referring to a person or people who identify as Indigenous, always capitalize “Indigenous”.

Phone numbers

Use parentheses around area codes. For international phone numbers, add the country code with a “+”, like +1 (999) 555-0123.

Use: (555) 555-5555

Avoid: 555-555-5555

Plurals

Usually, plurals should not have an apostrophe, even if they are abbreviations or numbers.  ATMs, Drs., and 1990s are all correct. Exception: Use an apostrophe in the plurals of letters and words if those plurals would be confusing without it. Single letters in particular can look confusing without an apostrophe.

Example: We loved the thank yous.

Example: Make a splash in this 90s-inspired GitHub tee.

Example: Dot your i’s and cross your t’s.

Punctuation

Don’t use punctuation in buttons, titles, or at the end of short calls to action. Also:

  • Use exclamation points sparingly
  • Use only one space after periods

Exceptions:

  • Use periods at the end of titles that include multiple sentences or phrases separated by periods or question marks, like “Full GitHub Universe. Half the price.”
  • Use periods at the end of subject lines that include multiple sentences or phrases separated by periods or question marks, like “Questions about GitHub Enterprise Cloud? We can help.”

Terms of Service

Treat GitHub’s Terms of Service like a proper noun. Always capitalize “Terms” and “Service”. Never use “ToS”. Refer to GitHub’s Privacy Statement in the same way.

Time

In regions that use the 24-hour clock (military time), write out the time in hh:mm convention, for example: 13:40. In regions that use the 12-hour clock, use “am” and “pm” with a space before and after and specify an abbreviated time zone, for example: “10 am PT”.

When writing timezone abbreviations, use “PT” and “ET instead of “PST” or “PDT” and “EST” or “EDT” no matter the region. Hopefully, readers will know what time of year it is.

Avoid: a.m., A.M., AM, p.m., P.M., PM

Use: am and pm

Words that can be tricky

For more tricky words and phrases, visit the “Terminology” section of this guide.

  • Admins
    • Use “admin” instead of “administrator” when possible. Spell out “administration” and “administrative” when referring to tools and other contexts.
  • Agile (e.g. agile development)
    • Don’t capitalize “agile” unless it’s starting a sentence.
  • Canceled, canceling, cancellation
    • Use “canceled” with one “l”. Note the switch from a single “l” to two with “cancellation.”
  • Email
    • Use “email”, not “e-mail”. Also, write email addresses in all lowercase.
  • Innersource
    • “Innersource” is one word. Don’t capitalize “innersource” unless it’s starting a sentence. Don’t use camelcase.
  • Internet
    • Don’t capitalize “internet” unless it’s starting a sentence. Fun fact: This is now a rule in the AP style guide.
  • Livestream
    • Use “livestream” as one word.
  • Login vs. log in
    • Adjective/noun: “Login” as one word can be either a noun or an adjective, for example: “your login information”.
    • Verb: “Log in” as two words is a verb. For example: you log in with your login information. Don’t use “login” in place of “username”.
    • Use “sign in” rather than “log in”.
    • Use “your username and password” rather than “login information”.
  • Meetup
    • “Meetup” is one word. It’s always lowercase unless it’s a specific meetup, for example: “GitHub Constellation Meetup”. Don’t use “meet-up” or “meet up”.
  • Mention
    • “Mention” referring to mentioning a username or team on GitHub can be used as a verb or noun. It should never include “@”.
  • Open source
    • Adjective: “Open source” is always lowercase, except when at the start of the sentence. You can use it as an adjective without a hyphen, as in “open source project” or “open source software”. It can be abbreviated after the first mention as “OSS”.
    • Noun: You can also use it on its own to refer to open source in general, as in “give back to open source”.
    • Verb: It’s also acceptable to use open source as a verb when referring to a project that has been “open sourced” or that you intend to “open source”.
  • Pull request
    • “Pull request” should never be abbreviated. It’s always lowercase unless it’s starting a sentence.
    • Avoid: Merge a PR
    • Use: Merge a pull request
  • Repository
    • “Repository” should never be abbreviated, except when saving space in a tweet. It’s always lowercase unless it’s starting a sentence.
    • Avoid: Create a new repo
    • Use: Create a new repository
  • Organization
    • “Organization” should never be abbreviated. It’s always lowercase unless it’s starting a sentence.
    • Avoid: Members of the org can clone a repository
    • Use: Members of the organization can clone a repository
  • Sign in/up (to)
    • “Sign in” and “Sign up” as two words are verbs. You “sign in to your account” and “sign in to see your tasks”.
    • Use “sign in” rather than “log in”.
  • Username
    • “Username” is one word and used to describe a person’s identifying name on GitHub. Never use “handle” or “login” in place of “username”.