Terminology guidelines

We use certain words in a special way. This word list defines our terminology to make sure we all use the same words for the same things.

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: This is the cloud / SaaS version of Sourcegraph at sourcegraph.com. It can be used freely for open source search, or as a SaaS version of Sourcegraph for 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.
  • 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”.

Term usage

Use thisNot thisWhy?
A
admin or site admin“administrator” or “site administrator”More conversational, per Quinn
alertsSourcegraph sends an alert to a notifier that sends a notification to the user. If we’re talking about what the product does, it’s alerting. If we’re talking about what the user experiences, it’s notifier/notifying.
B
Big codeboth capitalized
C
call sitecallsitePer Quinn
codebasecode baseMost commonly spelled as a single word.
code hostcodehostPer Quinn
code host connectionexternal serviceAligning terminology for clarity. Internally, we differentiate different ownership through the terms “user code host connections, “organization code host connections,” and “instance code host connections.”
configurationconfig“config” is OK in paths and navigation links
custom search pagesCustom search pages allow users to quickly search within a set of curated repositories, with data and interesting searches shared on that page. For example, “use this custom search page for Python 2-to-3 migration code”. When possible, use the more specific names Search scope page, a more specific name for a custom search page that describes search pages at /search/scope/SCOPENAME, or project search page, a more specific name for a custom search page that describes pages for projects. For example, the Kubernetes project search page to search across all Kubernetes code.
D
data structuredatastructureFavoring common usage
docsdocumentationOur voice is conversational and plainspoken. “Documentation” is overly formal, while “docs” is the common term today.
email addressemailThe two are both nouns, meaning different things.
F
fieldRefers to the first part in the key:value pair
filterFilter describes a parameter that can be added to a query to narrow down search results. A filter is always a parameter, but a parameter may not be a filter.
G
GoGolang
go to definitionjump to definition”, “jump-to-def”, or “j2d”
L
lifecyclelife cycleFavoring common usage
M
macOSOS X, OSX, MacOS, MacOSX
N
notifierSourcegraph sends an alert to a notifier that sends a notification to the user. If we’re talking about what the product does, it’s alerting. If we’re talking about what the user experiences, it’s notifier/notifying.
npmNPMBased on npm’s branding guidelines. For code, use npm if possible. In CamelCase contexts, use Npm. In SCREAMING_SNAKE_CASE contexts, use NPM.
O
OpenID ConnectOIDC
organization“company” or “team” or “org”
open source“open-source”, “Open Source”Favoring common usage
P
parameterParameter describes a key:value pair to filter behavior or change search behavior.
PostgreSQLPostgres, postgres, PgSQL, Postgresql, PostGres,Proper name
R
regex“regexp” or “regular expressions”This is to avoid confusion with RegExp in Javascript, and to avoid conflation with “exp” in Warcraft and other MMORPGs. This is relevant as we onboard younger users whose gaming experience is significant. If they’re used to “exp” being experience, they will have to pause for a moment to context-switch, thus creating confusion, even temporarily, which isn’t a good look.
repositoryrepoWe try to avoid abbreviations when possible. We habitually shorten words for concepts we work with every day until they become obvious to us, like repo, org, j2d, find-refs, PR, revs… but they aren’t obvious to outsiders, which can be confusing and result in a steeper learning curve for new users. In this spirit, we prefer “repository” and “repositories”.
S
saved searchesSaved searches describe complete searches that are used without needing to add more filters or expressions.
search expressionSearch expression describes a valid piece of a search that can be suggested and combined with other expressions to drill down on results.
search scopeversion contextUsed to describe drilling down in a pre-configured scope of repositories across the entire Sourcegraph instance (this persists for navigation and usage outside of the query bar search).
set up (v)/setup (n)Setup is a noun, set up is a verb (see notaverb.com/setup, although see note on descriptivism)
sign inlog inBecause it’s a better UX choice.
Sourcegraph“sourcegraph”, “SourceGraph”, or “sg”
T
tooltipstool-tips
U
URLurl