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.

Yes
  • for example
  • that is
  • as opposed to
  • through
  • Salesforce
No
  • e.g.
  • i.e.
  • v.
  • via
  • SF

Further reading:

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.

Yes
  • Added repository.
No
  • Repository was added.

Use passive voice when you don’t want to assign responsibility for an action. This can reduce tension in a message.

Yes
  • Your access token was invalid.
No
  • Invalid access token.

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.

Yes
  • Batch change created
No
  • Batch change has been created

Capitalization

Use Sentence case, not Title Case, everywhere. This includes:

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.

If it’s displayed within another product (e.g. a VS Code extension or Slack App) match the capitalization norms of that product.

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.

Yes
  • Create a new batch change
  • Save your changes
When necessary
  • Create batch change
  • Save changes

Write without rigidity.

Yes
  • Create an account to manage extensions.
No
  • An account is required to manage extensions.

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.

Yes
  • Choose a repository group.
No
  • Choose a repository group at the bottom right of this page.

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).
Yes
  • 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…
No
  • Thirty or more results
  • Last updated 2 days ago
  • Only five % of developers prefer working in an office.
  • More than six out of ten software professionals reported a significant increase…

Numbers over three digits get commas.

Yes
  • 144
  • 1,200

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.

Yes
  • Thursday, April 16
  • April 16
  • Apr 16

When possible, use natural language to describe dates.

Yes
  • Today
  • Yesterday
  • Tomorrow
  • This week
  • Next week
  • Two weeks from now

When date is written in numerals, the standard format is YYYY-MM-DD.

Yes
No
  • 08.09.2020
  • -2020

Percentages

Use the % symbol instead of spelling out “percent.”

Yes
  • 2%
No
  • Two 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.

Yes
  • Viewing results 100–150

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.

Yes
  • $10
  • $42
  • $1,500
  • $149.99
No
  • $10.00
  • $ 42
  • $1500
  • $149,99

When writing about monthly pricing, follow the convention: $0/mo. Do not use spaces.

Yes
  • $150/mo
No
  • $150 / month
  • $150/month
  • $150/pm

Use shorthand suffixes for shortening numbers in the thousands (k), millions (m), billions (b), and above. Prefer lower case suffixes.

Yes
  • $100b
No
  • $100,000
  • $100B
  • $100Bn
  • $100 billion

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.

Yes
  • +1 123 456 7890
No
  • 123 456 870
  • 1-123-456-789

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.

Yes
  • 5 pm
No
  • 5pm

Use an en dash (–) between times to indicate a time period. Don’t insert spaces before and after the en dash.

Yes
  • 8 am–12 pm
  • –18:00 pm

When referring to an amount of time, use numerals and the full word, with a space in between.

Yes
  • Saved 20 minutes ago
  • 30 seconds ago

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.

Yes
  • This batch change’s results are now available
  • This batch change is Jen’s favourite
  • Chris’s favourite batch change

Colons

Use a colon to offset a list.

Yes
  • Saved searches support three filters: diffs, commits, and repositories.

When a list begins with an interface label, capitalize the first word of the list.

  • Supported filters: Diffs, commits, and repositories.
  • Commas

    Prefer the Oxford or serial comma when writing a list.

    Yes
    • Saved searches support three filters: diffs, commits, and repositories.
    No
    • Saved searches support three filters: diffs, commits and repositories

    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).

    Yes
  • Our short-term plan is to…
  • No
    • In the short-term, we will work on…

    Use an en dash (–) to indicate a range or span, without spaces.

    Yes
    • 2–6 possible results

    Use an em dash (—) without spaces to separate clauses in paragraph copy.

    Yes
    • This new feature—a first in advanced workflow tooling—will empower developers around the world.

    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.

    Yes
    • Provides basic code intelligence for Java usi…
    No
    • Provides basic code intelligence for Java u…

    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.

    Yes
    • Updated to only show included filters (diffs, commits).
    No
    • Updated to only show included filters (diffs, commits.)

    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.

    Yes
    • Add an insight to “Test Dashboard”
    • “When quoting inside existing quotes, ‘Single quotes’ are the way to go”
    No
    • Add an insight to ‘Test Dashboard’
    • “When quoting inside existing quotes, avoid “double quoting””

    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.

    Yes
    • ‘Example’
    • “Example Two”
    No
    • ‘Example’
    • “Example two”

    Slashes

    Don’t use spaces between two terms separated by a slash.

    Yes
    • tool/editor
    No
    • tool / editor

    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.

    Yes
    • Now available in Winnipeg.
    No
    • Now available in WPG.

    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.

    Yes
    • Add a repo to start searching your code.
    No
    • If you don’t add a repo, you won’t be able to search your code.

    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.

    Yes
    • Remember to add a search filter
    No
    • Don’t forget to add a search filter

    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.

    Yes
    • Why are search scopes useful?
    No
    • Why search scopes are useful?

    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.

    Yes
    • Use the Phabricator integration to get Sourcegraph features in code review.
    No
    • Use the Sourcegraph Phabricator integration to get Sourcegraph features in code review (sounds repetitive and stilted).

    Always title case our name. Don’t abbreviate or add a space to our name.

    Yes
    • Sourcegraph
    No
    • SG
    • Source Graph

    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.
    No
    • Use Sourcegraph universal code search to…
    • With code insights you can…
    • Here’s how to use code search.
    • Our Code Intelligence Platform enables you to understand, fix, and automate across your entire codebase.

    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

    Yes
    • Batch Changes is available.
    • Code Insights is now available.
    No
    • Batch Changes are available.

    Refer to the natural noun of the product or feature directly.

    Yes
    • Batch Changes is available.
    No
    • The Batch Changes product is available.

    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.
    Yes
    • Sign up for Sourcegraph Cloud today.
    • Sourcegraph Cloud uses a single-tenant architecture with a dedicated, isolated instance for each organization.
    No
    • Request access to Sourcegraph Cloud today.
    • Best of all, we maintain Sourcegraph Cloud for you.

    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.
    Yes
    • 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.
    No
    • Sourcegraph cloud is our newest product.
    • You can run Sourcegraph on the Cloud.
    • This version of Sourcegraph is Cloud-based.

    Sourcegraph App

    When talking about the Sourcegraph app, we should:

    • Use Sourcegraph App as the formal product name. Avoid referring to the product as App.
    • 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 app or the app.

    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.

    Yes
    • I suggest you try out the Sourcegraph app.
    • Sourcegraph App: the best way for individuals to run Sourcegraph.
    No
    • Have you tried running Sourcegraph App?
    • You can run App on your local machine.

    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.

    Yes
    • they have a disability
    • person with disability
    • people living with disabilities
    No
    • they are disabled
    • disabled person

    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.

    Yes
    • Artisan
    No
    • Craftsman

    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”)

    Yes
    • After you’ve entered a search query
    No
    • Once you’ve entered a search query

    Right (could mean “correct,” “the opposite of left,” “politically conservative,” etc.)

    Yes
    • Choose the correct search
    No
    • Choose the right search

    Since (could refer to a point in time, or a synonym of “because”)

    Yes
    • Because you have a code monitor enabled, you can get email notifications for new events
    No
    • Since you have a code monitor enabled, you can get email notifications for new events

    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.

    Yes
    • Let’s get started
    • This information might change
    No
    • Let’s get crackin’
    • Take this with a grain of salt

    Instructions, references, and citations

    Use descriptive link text, never here.

    Yes
    No
    • For more information about Batch Changes, see documentation here.
    • If you encounter a problem, click here to file an issue.

    Use bold when referring to buttons in documentation.

    Yes
    • Click Add user.

    In documentation, use bold and a symbol, such as a bracket (>), to display menu option selections or sequences of user interface clicks.

    Example
    • File > Print indicates that a user selects the Print option from the File menu

    Never highlight a sentence in boldface font.

    Never directly reference the item (button, menu), just reference the label.

    Yes
    • Click Add user.
    No
    • Click the Add user button.

    Match the actual case of the UI text in other products even if it violates our style guide.

    Example
    • In the Single Sign On Url field, …

    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

    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.

    Example
    • Search query in video says ReadFile, but automatic transcript says read file. Transcript should be updated to ReadFile as shown in the video.