Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update style guide for OSS #19

Merged
merged 8 commits into from
Oct 16, 2018
Merged

Update style guide for OSS #19

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
59d057f
Move styleguide.md to root directory
Oct 10, 2018
7870861
Update styleguide to sentence case
Oct 10, 2018
0c6daa9
Update styleguide for OSS release
Oct 10, 2018
c955ad6
Update reference to OSS
Oct 10, 2018
04d7c8c
Updates
Oct 16, 2018
2a31592
Update wording
Oct 16, 2018
79cc86f
Update OSS and extensions callout
Oct 16, 2018
bcaa40a
Remove devops/admin
attfarhan Oct 16, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions website/STYLEGUIDE.md → STYLEGUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,7 @@ Our copy should be:
## General

- Seek to make content available, and coherent, to all peoples.
- Use Title Case for headers, buttons, features, and short lists.
- Use sentence case for non-header text. When sentence case is used, full punctuation should be used.
- Use sentence case across all text.
- Render proper nouns as their creators prefer ("GitHub" not "Github").
- Punctuation goes outside of quotation marks, except in marketing when displaying a quote.
- Use the most popular US English spelling and phrasing.
Expand All @@ -32,8 +31,9 @@ Assume the reader is a busy non-native English speaker.
### Referring to the Product and Features

- Sourcegraph: main product, prefer using this name unless you need to be more precise
- Sourcegraph Server: the form of our product that ships as the `sourcegraph/server` Docker image and runs on a single node
- Sourcegraph Data Center: the form of our product that runs on Kubernetes
- Sourcegraph Core: This build is the free tier of Sourcegraph built separately from Sourcegraph OSS.
- Sourcegraph Enterprise Starter: the tier of Sourcegraph that includes some features required for dev-ops/admins to deploy in their corporate environment.
- Sourcegraph Enterprise: the tier of Sourcegraph that includes all enterprise features for dev-ops/admins to deploy Sourcegraph at a large scale. Enterprise includes the cluster deployment option formerly called Data Center.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "for dev-ops/admins" because

  1. it is not clear who these personas are, specifically (ie they aren't defined anywhere)
  2. I would say "dev tools team members" is more accurate than "dev-ops", but that's a mouthful
  3. saying who is not necessary here

- Sourcegraph.com: the public instance of Sourcegraph for open-source code at https://sourcegraph.com
- Sourcegraph integrations: the general term for our integrations
- Sourcegraph['s] Phabricator integration
Expand All @@ -43,7 +43,9 @@ Assume the reader is a busy non-native English speaker.
- Sourcegraph['s] Firefox add-on
- Sourcegraph['s] Safari extension

When specifically distinguishing between Server and Data Center, it might help to say "the [single-node] Server deployment option" and "the Data Center [cluster] deployment option".
When referring to the build result of the open-source repository, use the name Sourcegraph OSS.

When specifically distinguishing between Core and Sourcegraph OSS it is important to note that Core is not built from the open-source code base and Sourcegraph OSS does not include the ability to upgrade, or Sourcegraph extensions. These are included in the Core version of Sourcegraph, that is built from the same code as Sourcegraph Enterprise and has the ability to upgrade later.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically Sourcegraph OSS supports Sourcegraph extensions, just not accessing the extension registry on Sourcegraph.com.

Copy link
Contributor Author

@francisschmaltz francisschmaltz Oct 16, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How's this: public Sourcegraph extensions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why that instead of just "...the ability to upgrade or access the extension registry on Sourcegraph.com"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to call out Sourcegraph extensions by name

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My version is more accurate. Referring to "public Sourcegraph extensions" implies that they can use private Sourcegraph extensions (which they can't, at least not in the same way that Sourcegraph Enterprise can). It also makes the mechanism unclear and sound less legitimate, as though we're disabling functionality instead of just limiting access to an online service.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to or access the extension registry on sourcegraph.com.


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. For example:

Expand Down