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.
Keep the following principles in mind when creating UI content for GitHub.
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:
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.
GitHub’s voice is:
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:
Read more about GitHub’s voice and tone in the Brand Guide.
If you’re in a hurry, these are the most important content guidelines to keep in mind, in no particular order.
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.
When referring to times, use am and pm, and not any other variation (a.m., A.M., AM).
Avoid using emojis, but when you do:
Be friendly and helpful, and avoid jargon. Do not blame the user.
In most cases, apologizing won't fix the problem. As a rule, do not apologize too much in any situation in the UI.
Do not try to be funny or humorous.
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.
Feedback message when transferring an issue, using the same term ("transfer") as the trigger button
Feedback message that uses a different term ("moving") than the trigger button
Use sentence case for form titles, labels, and fields. Do not include colons in form labels.
All labels and button text should be in sentence case, and not include punctuation.
Action labels should start with an imperative verb that clearly indicates what to expect.
Action labels can be shortened to only include an adjective and a noun.
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.
Set the context within the paragraph.
<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”.
Headings, labels and buttons should not include punctuation. In most cases, exclamation marks are not appropriate — most things aren't that exciting.
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. If you’re writing for a mobile app experience, use “tap”, instead of “click”.
When referring to a folder, use a code tag.
In most instances, address the user as "you" and items "owned" by the user as "your" or "yours".
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.
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 #design-systems channel.