Update style guide for OSS #19

francisschmaltz · 2018-10-10T17:32:10Z

Move style guide to root directory
Revert references for title case back to sentence case 😢
Update naming convention for OSS and paid tiers
Add callout that OSS is not the same as Core

dadlerj

A few comments, but lgtm!

dadlerj · 2018-10-12T21:28:07Z

STYLEGUIDE.md

-  - 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 OSS: the open source code for Sourcegraph. This is **not** the same as Sourcegraph Core.
+  - Sourcegraph Core: previously was called Sourcegraph Server, this build is the free tier of Sourcegraph built separately from Sourcegraph OSS.


previously was called Sourcegraph Server

This isn't exactly right, since what was previously called "Server" really now maps to both "Core" and "Enterprise Starter" in the new model

Should I remove this?

Yeah, I'd just remove that, because it's not correct. If you prefer, you could replace it with something else that explains how the old "Server" is now both "Core" and "Enterprise Starter" but it's your call on whether that's necessary at all.

dadlerj · 2018-10-12T21:28:45Z

STYLEGUIDE.md

+  - Sourcegraph OSS: the open source code for Sourcegraph. This is **not** the same as Sourcegraph Core.
+  - Sourcegraph Core: previously was called Sourcegraph Server, 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"

dadlerj · 2018-10-12T21:40:44Z

STYLEGUIDE.md

@@ -43,7 +44,7 @@ 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 specifically distinguishing between Core and OSS it is important to note that Core is not built from the OSS code base and OSS does not include tracking data, 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.


does not include tracking data

We don't collect anything from "dev"/oss, but we also haven't ripped this code out of the common codebase. I'd remove this for now.

sqs · 2018-10-12T23:03:23Z

STYLEGUIDE.md

@@ -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 for all text. When sentence case is used, full punctuation should be used.


Full punctuation (periods, etc.) should not be used in many cases: buttons, labels, nav links, headlines, etc. I think you can just omit the "When sentence case is used, full punctuation should be used." sentence and it will be clear.

BTW, the model for us to follow is GitHub. They have very consistent style in all their pages and materials, and they use sentence case. If in doubt about a rule, look at what GitHub does.

sqs · 2018-10-12T23:04:59Z

STYLEGUIDE.md

@@ -32,8 +31,10 @@ 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 OSS: the open source code for Sourcegraph. This is **not** the same as Sourcegraph Core.


open-source (with hyphen when used as an adjective)

Also I would not include Sourcegraph OSS in this list, as it's not really a product. You could mention it in a bullet point underneath and say something like "When referring to the build result of the open-source repository, use the name Sourcegraph OSS."

sqs · 2018-10-16T00:39:40Z

@francisschmaltz Ping on this, I'd like to have this merged so I can link to it from the new docs

francisschmaltz · 2018-10-16T00:47:45Z

@sqs Updated from these notes

sqs

2 minor comments, LGTM after addressing them

sqs · 2018-10-16T01:08:22Z

STYLEGUIDE.md

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


Remove "for dev-ops/admins" because

it is not clear who these personas are, specifically (ie they aren't defined anywhere)

I would say "dev tools team members" is more accurate than "dev-ops", but that's a mouthful

saying who is not necessary here

sqs · 2018-10-16T01:08:49Z

STYLEGUIDE.md

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


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

How's this: public Sourcegraph extensions.

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

I want to call out Sourcegraph extensions by name

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.

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

Francis Schmaltz added 3 commits October 10, 2018 10:20

Move styleguide.md to root directory

59d057f

Update styleguide to sentence case

7870861

Update styleguide for OSS release

0c6daa9

francisschmaltz requested review from dadlerj and sqs October 10, 2018 17:32

francisschmaltz self-assigned this Oct 10, 2018

Update reference to OSS

c955ad6

dadlerj approved these changes Oct 12, 2018

View reviewed changes

dadlerj reviewed Oct 12, 2018

View reviewed changes

sqs reviewed Oct 12, 2018

View reviewed changes

Updates

04d7c8c

sqs approved these changes Oct 16, 2018

View reviewed changes

dadlerj mentioned this pull request Oct 16, 2018

docs: update Sourcegraph extension docs #28

Merged

Francis Schmaltz added 2 commits October 15, 2018 18:41

Update wording

2a31592

Update OSS and extensions callout

79cc86f

sqs referenced this pull request in sourcegraph/docs.sourcegraph.com Oct 16, 2018

Added a Makefile for simplicity.

fe4e608

Remove devops/admin

bcaa40a

attfarhan merged commit 2ec613e into master Oct 16, 2018

attfarhan deleted the fs/update-styleguide branch October 16, 2018 20:27

leehambley mentioned this pull request Jan 21, 2019

Fix link to styleguide in the documentation dir. sourcegraph/sourcegraph#1972

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update style guide for OSS #19

Update style guide for OSS #19

francisschmaltz commented Oct 10, 2018

dadlerj left a comment

dadlerj Oct 12, 2018

francisschmaltz Oct 12, 2018

dadlerj Oct 12, 2018

dadlerj Oct 12, 2018

dadlerj Oct 12, 2018 •

edited

Loading

sqs Oct 12, 2018

sqs Oct 12, 2018

sqs Oct 12, 2018

sqs commented Oct 16, 2018

francisschmaltz commented Oct 16, 2018

sqs left a comment

sqs Oct 16, 2018

sqs Oct 16, 2018

francisschmaltz Oct 16, 2018 •

edited

Loading

sqs Oct 16, 2018

francisschmaltz Oct 16, 2018

sqs Oct 16, 2018

francisschmaltz Oct 16, 2018

Update style guide for OSS #19

Update style guide for OSS #19

Conversation

francisschmaltz commented Oct 10, 2018

dadlerj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dadlerj Oct 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sqs commented Oct 16, 2018

francisschmaltz commented Oct 16, 2018

sqs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

francisschmaltz Oct 16, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dadlerj Oct 12, 2018 •

edited

Loading

francisschmaltz Oct 16, 2018 •

edited

Loading