We have an editorial style to help us keep our copy clear and consistent, and specific guidelines to write and structure content to make it easy for users to understand and act on.
Remember, we strive for effectiveness over correctness. Use these guidelines as a reference, not an authority, and always prioritize what's most effective for our target users.
Use the most popular US English spelling and phrasing.
Avoid abbreviations, acronyms, latinisms, and jargon when possible. Use complete English words for clarity.
Further reading:
- "Acronyms Seriously Suck" from Elon Musk.
Try to avoid adjectives and adverbs. Using adjectives and adverbs (for example, it’s “easy” to get started with Sourcegraph) shapes perception and sets expectations, and can inadvertently lead to a negative emotional experience for our users.
Instead, look for opportunities to capture the same meaning through other forms. What makes an “easy” book easy relative to other books? Can that be used as a scale of relative difficulty?
Generally, use active voice and avoid passive voice. In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.
Use passive voice when you don’t want to assign responsibility for an action. This can reduce tension in a message.
The best way to determine if you’ve gone passive is to check for zombies.
Use present tense to describe the result of actions.
Use Sentence case, not Title Case, everywhere. This includes:
- Headings and subheadings
- UI copy
- Buttons
- Links
- Error messages
- Confirmation messages
- Success messages
- Placeholders
- Input labels
All-caps should be used sparingly and only for specific purposes (all-caps copy is less accessible and harder to read). Never use all-caps within a sentence.
Render proper nouns as their creators/trademarks prefer: Docker, Bitbucket, GitLab, GitHub, React, Git, JavaScript, TypeScript.
Use contractions like “we’ll” or “there’s!” They make our writing more conversational.
However, don’t rely on contractions alone for a conversational voice.
Our voice is conversational. When we’re talking, we connect words with articles like “the,” “for,” “these,” and “an.” If we remove these from our writing, it makes our copy feel stiff and complicated. We can be flexible, though. If space is a limitation, the article can be omitted.
Write without rigidity.
Avoid any instructions or language that requires the user to see the layout or design of a page or element. This assumes ability and may not reflect the actual layout of the page at a given moment in time.
- Spell out numbers 1–9 except for percentages and ranges.
- Use numerals for 10 upwards.
- Always use the numeral for ordinals (numbers that tell the position of something in a list).
- 30+ results
- Last updated two days ago
- Only 5% of developers prefer working in an office.
- More than 6 out of 10 software professionals reported a significant increase...
Numbers over three digits get commas.
Spell out the day of the week and the month whenever possible. Abbreviate when space is a limitation. When abbreviated in interface headings and labels, do not use a period.
When possible, use natural language to describe dates.
When date is written in numerals, the standard format is YYYY-MM-DD.
Use the % symbol instead of spelling out “percent.”
Use an en dash (–) to indicate a range or span of numbers. Do not use spaces before and after the en dash.
An en dash is slightly wider than a hyphen (-) but narrower than an em dash (—).
When writing about US currency, use the dollar sign ($) before the amount. Prefer to omit the cents. Use commas to separate thousands, and when unavoidable, a period to separate the cents. Do not insert a space between the dollar sign and the number.
When writing about monthly pricing, follow the convention: $0/mo. Do not use spaces.
Use shorthand suffixes for shortening numbers in the thousands (k), millions (m), billions (b), and above. Prefer lower case suffixes.
Use the country code, prefixed with +, without a space. Use spaces between sets of numbers for readability. The number of digits in each set of numbers may differ by country.
When writing about a time of the day, use numerals and lowercase am or pm, with a space in between. Use 12-hour time.
Use an en dash (–) between times to indicate a time period. Don’t insert spaces before and after the en dash.
When referring to an amount of time, use numerals and the full word, with a space in between.
Apostrophes are usually used to make a word possessive. If the word already ends in an s and it’s singular, you also add an’s. If the word ends in an s and is plural, just add an apostrophe.
Watch out for dumb apostrophes ('). These are a relic of typewriters, and can be identified by how they’re straight rather than curly. Always use typographic apostrophes (‘).
In Markdown content in our handbook you don't need to worry about this rule: dumb apostrophes are automatically replaced with typographic quotation marks.
Use a colon to offset a list.
Prefer the Oxford or serial comma when writing a list.
Use a hyphen (-) without spaces before and after to link words into a single phrase. This is only necessary where the phrase appears in front of a noun to describe it (acting as an adjective).
Use an en dash (–) to indicate a range or span, without spaces.
Use an em dash (—) without spaces to separate clauses in paragraph copy.
Use ellipses to indicate that a line of copy has been clipped before the end. This is typically used when only a single line of copy will fit, but the content itself is too long. Avoid this when possible.
When ellipses are used to clip a line of copy, clip after at least 2 characters.
Use periods in complete sentences. Don’t use periods in headlines or labels. Periods go inside quotation marks. They go outside parentheses ( ) when the contained text is part of a larger sentence, and inside when the contained text stands alone.
When quoting content, use double quotation marks. Use single quotation marks to quote content within an existing quote.
In HTML, using <q></q> will automatically apply the correct quotation marks for nested <q> tags.
- Add an insight to “Test Dashboard”
- “When quoting inside existing quotes, ‘Single quotes’ are the way to go”
Watch out for dumb quotation marks (' and "). These are a relic of typewriters, and can be identified by how they’re straight rather than curly. Always use typographic quotation marks (‘ and ’, “ and ”).
In Markdown content in our handbook and blog you don't need to worry about this rule: dumb quotation marks are automatically replaced with typographic quotation marks.
In HTML, the easiest way to add the appropriate typographic quotation marks is to wrap the quote in <q></q> instead of manually quoting.
Don't use spaces between two terms separated by a slash.
Spell out all city names.
When written in paragraph copy, write out country, state, and province names on the first mention. On subsequent mentions, abbreviating is fine.
Use positive language rather than negative language. Positives are easier to read and process than negatives. One way to detect negative language is to look for words like “can’t,” “don’t,” etc.
If a sentence begins with a negative word, the sentence’s implication can be misinterpreted as negative.
A common error when writing questions is not constructing the sentence as a question. Usually, this can be fixed by changing the word order.
We describe ourselves with a few different names depending on context, and we should use the right term at the right time.
- Sourcegraph: Main product. This name is always preferred unless you need to clarify between the 3 deployment methods for Sourcegraph below.
- Sourcegraph self-hosted: On-premises and self-managed version of Sourcegraph.
- Sourcegraph Cloud: This is the cloud instance of Sourcegraph at sourcegraph.com, used both for open source search as well as individual accounts for connecting public or private code.
- Managed Sourcegraph instance: Private Sourcegraph instances managed and provisioned by the Sourcegraph team.
- Sourcegraph integrations: The general term for our integrations. When referencing specific integrations:
- Sourcegraph(’s) Phabricator integration
- Sourcegraph(’s) GitHub integration
- Sourcegraph(’s) browser extensions
- Sourcegraph(’s) Chrome extension
- Sourcegraph(’s) Firefox add-on
- Sourcegraph OSS: When referring to the build result of the open source repository.
You don't need to use the full name of the product each time you refer to it, but don't use a shortened name that could be confused with an official name.
Always title case our name. Don’t abbreviate or add a space to our name.
Only use we and our (as in “our GitHub integration”) in informal documents. In documentation or marketing material, depending on the context, just avoid it, or use “the” or “Sourcegraph”.
We capitalize product names. Qualify product names with Sourcegraph $FEATURE on first reference. Don't capitalize product names when referencing them generically or in context of taking an action.
List of product names:
- Batch Changes
- Code Insights
- Code Intelligence
- Universal Code Search
- With Sourcegraph Universal Code Search you can...
- You can search across all your repositories with Universal Code Search.
- Companies benefit from a universal code search tool because...
- Sourcegraph Batch Changes are... Batch Changes allow you to...
- To create a batch change...
We don't capitalize features or integrations.
- Use the Phabricator integration to...
- Want to use this in your code review tool? Use Sourcegraph’s GitHub integration.
- Here’s how to use code search.
- Use the Phabricator Integration to... (the capital “I” makes it into a proper noun, which implies it’s a product.”)
- Want to use this in your code review tool? Use Sourcegraph for GitHub. (Implies that “Sourcegraph for GitHub” is an official product name.)
- Here’s how to use Code Search.
Use the natural plural/singular form. If a product or feature name is a plural noun, treat it as a plural noun.
Refer to the natural noun of the product or feature directly.
We design and build our platforms with a human-centered point of view. Whenever we write something for our digital platforms, we need to write in a way that’s compassionate, inclusive, and respectful.
Here are some specific guidelines for how we write about people.
Avoid disability-related idioms like “lame” or “falling on deaf ears.”
Default to person-first language rather than identity-first language.
Do not use the term “edge cases” to describe users living with disabilities. This term further marginalizes people already living on the margins. Instead, use the term “stress cases.”
Don’t call groups of people “guys.” Don’t call women “girls.”
Avoid gendered terms.
It’s okay to use “they” as a singular pronoun. If there’s no inherent purpose to specifying a gender, default to “they.”
Use lower-case “deaf,” “hard of hearing,” or “hearing loss” as adjectives to describe someone with hearing loss.
Use lower-case “blind” to describe someone who is unable to see. Use “low vision” or “vision loss” as adjectives to describe a person with limited vision.
Some words to watch out for:
Once (could mean “one time,” “after,” “in the past,” or “when”)
Right (could mean “correct,” “the opposite of left,” “politically conservative,” etc.)
Since (could refer to a point in time, or a synonym of “because”)
In most languages, idioms are commonly-known phrases packed with meaning. However, idioms don’t often translate into other languages. They can also create confusion for translators that have English as an additional language. It’s better to avoid using idioms at all.
Use bold when referring to buttons in documentation.
In documentation, use bold and a symbol, such as a bracket (>), to display menu option selections or sequences of user interface clicks.
Never highlight a sentence in boldface font.
Never directly reference the item (button, menu), just reference the label.
Match the actual case of the UI text in other products even if it violates our style guide.
Refer to and cite other documents by quoting and linking their title. The quotation marks are not linked, and the period goes outside the quotes.
- For more information, see “Monitoring and tracing”.
Don’t use examples to compensate for poor documentation. Avoid “cutesy” examples.
For consistency, all examples should use the following names (as appropriate).
- People: Logan, Morgan, Jordan, Riley, Cris, Cami, Dani, Alex, Chidi, Akira, Sam (or other gender-neutral first names, instead of the traditional Alice, Bob, Charles...)
- Usernames:
logan,morgan,jordan,riley,cris,cami,dani,alex,chidi,akira,sam - Hostnames: example.com and subdomains of example.com (avoid using real names such as
mycompany.com) - Email addresses: [email protected], [email protected]
- URLs: https://sourcegraph.example.com (assume HTTPS)
- Organizations: ABC Organization (
abc-org)
Treat all supported platforms equally. For example, don’t give instructions for Chrome or GitHub in a way that implies they are the default.
Wherever possible, link to a 3rd-party tool’s existing documentation over explaining it in our own documentation, because our explanation can easily become outdated.
Prefer the https URL scheme (https://example.com not http://example.com). The only exception is if the site actually doesn’t support HTTPS.
Provide caption tracks and transcripts for all video and audio media. The style and mechanics in these content guidelines should be followed where possible, particularly with product and feature names, capitalization, and punctuation.
While automatic transcription tools like Otter are recommended, the generated transcript must be treated as a first draft. Review the transcript for accuracy, formatting, and style conventions.
Where a narrator describes code, search queries, or other text that also appears in a video, match the captions to the text and formatting shown in the video.