Style and mechanics
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.
Abbreviations, acronyms, latinisms, jargon
Avoid abbreviations, acronyms, latinisms, and jargon when possible. Use complete English words for clarity.
- ”Acronyms Seriously Suck” from Elon Musk.
Adverbs and adjectives
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?
Active voice vs. passive voice
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
- Error messages
- Confirmation messages
- Success messages
- 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.
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 directional language
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
Use the % symbol instead of spelling out “percent.”
Ranges and spans
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.
Dashes and hyphens
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
- Add an insight to “Test Dashboard”
- “When quoting inside existing quotes, ‘Single quotes’ are the way to go”
Watch out for dumb quotation marks (
"). These are a relic of typewriters, and can be identified by how they’re straight rather than curly. Always use typographic quotation marks (
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.
Positive vs. negative
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.
Use positive words when talking about positive things
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.
Writing about ourselves
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 Dedicated, single-tenant Sourcegraph instances managed and provisioned by the Sourcegraph team. This was previously referred to as “managed instances.”
- Sourcegraph.com / “dotcom”: This is the service publicly available at sourcegraph.com. It can be used to search top open source repositories.
- Sourcegraph App: This is the single-user app version of Sourcegraph.
- Sourcegraph OSS: When referring to the build result of the open source repository.
- 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
- Code intelligence platform: Use when referring to our category or our entire suite of products and features.
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 Search
We do not capitalize our category name (code intelligence platform) or platform positioning.
- With Sourcegraph 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 is… Batch Changes allows you to…
- To create a batch change…
- You can create batch changes for various purposes, such as upgrading dependencies across…
- Sourcegraph is a code intelligence platform that enables you to understand, fix, and automate across your entire codebase.
- You can get started with Sourcegraph Cloud today.
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.
- 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.)
If a product name is a plural noun, treat it as a singular noun. If a feature is a plural noun, treat it as a plural noun. When referencing products generically or in context of taking an action, use the natural plural/singular form
Refer to the natural noun of the product or feature directly.
When talking about Sourcegraph Cloud, we should:
- Position Sourcegraph Cloud as something you sign up for, not something you request access to.
- Use language that highlights the absolute benefits of single-tenant Cloud: dedicated, isolated, secure, etc.
- Only mention comparative benefits, like no maintenance, scaling, or upgrading when making a direct comparison to Cloud vs Self-hosted.
- Sign up for Sourcegraph Cloud today.
- Sourcegraph Cloud uses a single-tenant architecture with a dedicated, isolated instance for each organization.
Be careful to only capitalize the word “Cloud” in certain situations:
- Capitalize “Cloud” when referring directly to the product as a proper noun.
- Capitalize “Cloud” when using it as shorthand that refers directly to the product. In this case, it should still be treated as a proper noun. Using “Cloud” as shorthand should only be done to avoid the repitition of saying “Sourcegraph Cloud” repeatedly.
- Do not capitalize “cloud” when referring to it as a common noun or when referring to general cloud technology.
- We recommend you use Sourcegraph Cloud. With Cloud, you can use X, Y, and Z features.
- Cloud, our newest offering, features X Y Z benefits.
- You can now run Sourcegraph on the cloud.
When talking about the Sourcegraph app, we should:
Sourcegraph Appas the formal product name. Avoid referring to the product as
- Only use the formal name,
Sourcegraph App, when trying to convey the difference between this product and other Sourcegraph products.
- When talking about or describing the product otherwise, refer to it in simple human language, such as
the Sourcegraph appor
Tactically, the formal name
Sourcegraph App can be used for titles and headers in written material when we want to call out that specific product. When referencing the app elsewhere (such as in descriptive text on a web page or docs page), it is preferred to refer to it as
the Sourcegraph app.
Writing about people
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.”
Gender and sexuality
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.
Avoid words with multiple meanings
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.
Instructions, references, and citations
Use descriptive link text, never
- See Batch Changes documentation for more information.
- If you encounter a problem, file an issue.
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…)
- Hostnames: example.com and subdomains of example.com (avoid using real names such as
- Email addresses: firstname.lastname@example.org, email@example.com
- URLs: https://sourcegraph.example.com (assume HTTPS)
- Organizations: ABC Organization (
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.
https URL scheme (
http://example.com). The only exception is if the site actually doesn’t support HTTPS.
Caption tracks and transcripts
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.