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.
Spelling
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.
Further reading:
- ”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.
Present tense
Use present tense to describe the result of actions.
Capitalization
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.
Contractions
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.
Conversational writing
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.
Numbers
- 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).
Numbers over three digits get commas.
Dates
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.
Percentages
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 (—).
Money
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.
Telephone numbers
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.
Time
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.
Punctuation
Apostrophes
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.
Colons
Use a colon to offset a list.
Commas
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.
Ellipses
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.
Periods
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.
Quotation marks
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.
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.
Slashes
Don’t use spaces between two terms separated by a slash.
Places
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.
Writing questions
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 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”.
Product names
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.
Yes
- 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.
Feature names
We don’t capitalize features or integrations.
Yes
- Use the Phabricator integration to…
- Want to use this in your code review tool? Use Sourcegraph’s GitHub integration.
No
- 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.
Sourcegraph Cloud
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.
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.
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.
Disability
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.”
Hearing
Use lower-case “deaf,” “hard of hearing,” or “hearing loss” as adjectives to describe someone with hearing loss.
Vision
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”)
Avoid idioms
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 here.
Yes
- 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.
Example
- For more information, see “Monitoring and tracing”.
Using examples
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: logan@example.com, morgan@example.com
- URLs: https://sourcegraph.example.com (assume HTTPS)
- Organizations: ABC Organization (
abc-org)
Technical writing
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.
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.