Skip to content

Content

These guidelines are specific to and focused on GitHub product interfaces. Your first port of call for general content guidelines should be GitHub’s Content Style Guide, followed by the Microsoft Style Guide.

UI content principles

Keep the following principles in mind when creating UI content for GitHub.

1. Keep it clear

Aim for a seventh-grade or below reading level. This means you should write text that is straightforward, without trying to be creative with words.

There are some useful tools you can use to test your content for simplicity and reading level:

2. Keep it consistent

Refer to the same actions, sections, labels, landing pages, and so on, the same way across the product. But don’t sacrifice clarity over consistency.

Voice and tone

GitHub’s voice is:

  • Clear but not cold
  • Conversational but not jargon-y
  • Inclusive but not disingenuous
  • Helpful but not overly-prescriptive

Tone is how you express personality and mood depending on the situation. GitHub’s tone is almost always informal and positive, with adjustments when needed depending on the channel, audience, and emotional state of the audience.

You should consider the context of when a user will read something, keeping in mind that:

  • Humor isn’t welcome in all situations, for example: in errors, when waiting, or when something fails.
  • Error messages should be understandable by humans.

Read more about GitHub’s voice and tone in the Brand Guide.

Top 10 rules

If you’re in a hurry, these are the most important content guidelines to keep in mind, in no particular order.

  • Write in plain English, don’t sound like a robot.
  • Be brief, remove unnecessary words like adjectives and adverbs.
  • Use active voice.
  • Use sentence case, and when in doubt, don’t capitalize.
  • Always capitalize GitHub correctly.
  • Avoid gendered language.
  • Do not use slang or culturally-specific references.
  • Do not use “here” or “click here” in calls to action.
  • Be very thoughtful when introducing humor to the interface.
  • Have someone else proofread your text.

Content guidelines

Acronyms and abbreviations

Use acronyms when they are more widely used than the spelled out term.

“Pull request” should never be abbreviated. It’s always lowercase unless it’s starting a sentence.

Dates and time

When referring to times, use am and pm, and not any other variation (a.m., A.M., AM).

Emojis

Avoid using emojis, but when you do:

  • Use them only at the end of a sentence
  • Use only well-recognized emojis
  • Do not repeat emojis
  • Use emojis that will work well in both dark and light modes

Error messages

Be friendly and helpful, and avoid jargon. Do not blame the user.

Do
Do: Be friendly and helpful. Example: Enter a name, Your name must be between 2 and 20 characters
Don't
Don't: Blame the user and use jargon. Example: You forgot to add your name, Error 1234567890

Be specific.

Do
Do: Be specific. Example: Enter a credit card number
Don't
Don't: Be vauge. Example: Field required

In most cases, apologizing won't fix the problem. As a rule, do not apologize too much in any situation in the UI.

Do
Do: State what has happened. Example: All checks failed
Don't
Don't: Do not apologize excessively in the UI. Example: Sorry, all checks failed

Do not try to be funny or humorous.

Do
Do: Clearly state the outcome. Example: Some checks failed
Don't
Don't: Try to be humorous or funny. Example: Oops, some checks failed

Feedback

Feedback should be clear and reassuring, using the same terms used by the UI elements that triggered it. Don't try to be funny, and avoid jargon.

Do
Do: Write feedback to be clear and reassuring. Example: Issue transfer in progress

Feedback message when transferring an issue, using the same term ("transfer") as the trigger button

Don't
Don't: Use language in feedback that is different from its trigger. Example: Moving the issue

Feedback message that uses a different term ("moving") than the trigger button

Forms

Use sentence case for form titles, labels, and fields. Do not include colons in form labels.

Labels and buttons

All labels and button text should be in sentence case, and not include punctuation.

Do
Do: Leave out punctuation in labels and buttons. Example: Save email preferences, 1 linked pull request, 12 days ago
Don't
Don't: Include punctuation in labels and buttons. Example: Save email preferences., 1 Linked pull request, 12 Days ago
When a sentence or label starts with a number (for example, “2 references”), the number is the first word, and the rest of the sentence should be in lowercase.

Action labels should start with an imperative verb that clearly indicates what to expect.

Do
Do: Start action labels with an imperative verb. Example: Save preferences

Action labels can be shortened to only include an adjective and a noun.

Do
Do: Shorten action labels. Example: New issue

Use “sign in” rather than “log in”.

Link text should be meaningful and unique, with as few duplicated references as possible to prevent confusion. Ideally the link itself, or, alternatively, its programmatically determined context, should provide information about where the link will take you, and help users decide whether to follow the link. Examples of programmatically determined context can be aria labels, or text within the same paragraph as the link.

Do
Do: Set context and provide information that relates the link's location. Example: You can find out more about our speakers at the GitHub Universe site

Set the context within the paragraph.

Do
<a href="/pricing">
<img src="pricing.jpg" alt="">
Pricing information
</a>

Set the context of the image link from the text within the same container.

Never say “here” or “click here”.

Don't
Don't: Never say 'here' or 'click here' in links. Example: Click here to find out more about our speakers at GitHub Universe.

Punctuation

Headings, labels and buttons should not include punctuation. In most cases, exclamation marks are not appropriate — most things aren't that exciting.

Do
Do: Remove punctuation from headings and labels. Example: No code scanning alerts found
Don't
Don't: In most cases don't use exclamation marks. Example: No code scanning alerts found!

References to UI

When referring to unclickable page names and sections, write them as they appear in the interface in quotation marks.

Do
Do: Refer to unclickable sections as they are written in the UI and wrapped in quotes. Example: Go to the 'Email notifications settings' section.

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. If you’re writing for a mobile app experience, use “tap”, instead of “click”.

Do
Do: Write button and links in bold. Example: Click Save with Save in bold

When referring to a folder, use a code tag.

Do
Do: Write a folder name with the code tag. Example: Open the <code>docs</code> folder

Subject

In most instances, address the user as "you" and items "owned" by the user as "your" or "yours".

Do
Do: Address the user as you. Example: Update your profile
Don't
Don't: Address the user or things they own with 'I' or 'my'. Example: Update my profile

Some exceptions exist and are usually related to legal language, such as when a user needs to agree to terms, or confirm a destructive action.

Do
Do: Exception to address the user as I with legal terms. Example: I have read the Terms of Service, I understand, convert this issue to a discussion

What to avoid

  • Do not say that something is “easy”, “quick”, or that the user “just” needs to do something.
  • Do not capitalize common terms. Only proper nouns and product names should be capitalized.
  • Do not use emoji in UI content, or to replace words.
  • Use the word “and” instead of an ampersand or the “+” sign.
  • Do not use exclamation marks to indicate excitement, most actions aren’t.
  • Do not use the greater than and less than symbols to indicate steps in a flow.
  • Do not use semicolons: they are hard to get right and can be replaced by a period most times.

How to get help

If you need clarification and can’t find an answer in the GitHub’s Content Style Guide or the Microsoft Style Guide, or would like your UI content to be reviewed, please start a discussion in github/primer and someone in the team will get back to you. If your query is urgent, you can ask directly in the #primer channel.

Edit this page on GitHub
4 contributorsmamusoyailiashygeecolebemis
Last edited by mamuso on August 10, 2021