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.
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
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
Don’t use ampersands unless you’re referencing a brand name, for example: Proctor & Gamble.
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
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
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
We always use the Oxford comma. Refer to the Chicago Manual for comma guidelines.
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
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”.
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.
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
Don’t use ellipses unless you’re omitting words from a quote.
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:.
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.
Use exclamation points sparingly. Too many can feel disingenuous and overwhelming.
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
When referring to folders in a repository, use a code block with backticks.
Example: Add an issue template to the
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 “
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.
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.
Your GitHub Developer Program membership includes:
Avoid “master” when referring to the original branch or database. Use “main branch” or “primary database” unless context calls for another alternative.
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.
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.
Please use only one space after periods.
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”.
Use parentheses around area codes. For international phone numbers, add the country code with a “+”, like +1 (999) 555-0123.
Use: (555) 555-5555
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.
Don’t use punctuation in buttons, titles, or at the end of short calls to action. Also:
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.
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
For more tricky words and phrases, visit the “Terminology” section of this guide.