Merge pull request #2233 from segmentio/DOC-378

Edits to "Getting Started with Segment" and "What is Segment?" [DOC-378]

Author: stayseesong

src/_data/sidenav/main.yml

@@ -3,9 +3,9 @@ sections:
 - section_title: Getting Started
   section:
   - path: /getting-started
-    title: Getting Started With Segment
-  - path: /getting-started/01-what-is-segment
     title: What is Segment?
+  - path: /getting-started/01-what-is-segment
+    title: How Segment Works
   - path: /getting-started/02-simple-install
     title: A Basic Segment Installation
   - path: /getting-started/03-planning-full-install

src/getting-started/01-what-is-segment.md

@@ -1,52 +1,52 @@
 ---
-title: What is Segment?
+title: How Segment Works
 ---
 
-This page introduces important terms and concepts about Segment that you should be familiar with before you start a Segment installation.
+In a nutshell, the Segment libraries ([Sources](/docs/connections/sources/catalog/)) generate messages about what's happening in your site or app, and send them to the Segment servers. Segment then translates the content of those messages into different formats for use by other tools (which Segment calls [Destinations](/docs/connections/destinations/)), and sends the translated messages to those tools. The Segment servers also archive a copy of the data, and can [send data to your storage systems](/docs/connections/storage/) (such as databases, warehouses, or bulk-storage buckets).
 
 
-In the simplest form, the Segment libraries ("[Sources](/docs/connections/sources/catalog/)") generate messages about what's happening in your site or app, and send them to the Segment servers. Segment then translates the content of those messages into different formats for use by other tools (which we call '[Destinations](/docs/connections/destinations/)'), and sends the translated messages to those tools. The Segment servers also archive a copy of the data, and can [send data to your storage systems](/docs/connections/storage/) (such as databases, warehouses, or bulk-storage buckets).
-
-
-## The Segment Platform
+## Overview
 
 ![](images/subwaymap-2.png)
 
-The first two parts of the Segment platform are the [Segment Spec methods](/docs/connections/spec/), which are how you collect interaction data from your interfaces, and the [Segment Sources](/docs/connections/sources/), which you package with your interfaces to collect and route that data.
+[Segment Spec methods](/docs/connections/spec/) are how you collect interaction data from your interfaces, and the [Sources](/docs/connections/sources/) are what you package with your interfaces to collect and route the data.
 
-Once you've collected your interaction data, there are several different things you can do with it:
+Once you've collected your interaction data, there are several different actions you can take:
 - Send it to [Destinations](/docs/connections/destinations/), which receive the data from any number of sources in real time
-- Send it to [Warehouses](/docs/connections/storage/) (and other bulk storage tools), which hold your raw event schemas and update on regular intervals
-
-You can also enrich the customer data you collect by [connecting data from your other tools](/docs/connections/sources/catalog/#cloud-apps), and then collect it in a warehouse to monitor performance, inform decision-making processes, and create uniquely customized user experiences. You can also use [Personas](/docs/personas/), our identity resolution tool, to unify data from individual users to gain a holistic understanding of their actions.
+- Send it to [Warehouses](/docs/connections/storage/) and other bulk storage tools, which hold your raw event schemas and update on regular intervals
+- Enrich the customer data you collect by [connecting data from your other tools](/docs/connections/sources/catalog/#cloud-apps), and then collect it in a warehouse to monitor performance, inform decision-making processes, and create uniquely customized user experiences.
+- Use [Personas](/docs/personas/), Segment's identity resolution tool, to unify data from individual users to gain a holistic understanding of their actions.
 
 
-## Where data comes from
+## Sources for collecting data
 
-You can quickly implement Segment’s tracking libraries across several different platforms.
+You can collect data by implementing Segment’s tracking libraries as your Sources:
+- [Analytics.js](/docs/connections/sources/catalog/libraries/website/javascript/), the Segment Javascript source, is the most powerful way to track customer data from a website. Segment recommends it as the default installation for any website.
+- [The Segment Mobile SDKs](/docs/connections/sources/catalog/#mobile) are the best way to simplify tracking in your iOS, Android, and Xamarin apps. Segment recommends them over server-side sources as the default installation for any mobile app.
+- [Server-side sources](/docs/connections/sources/catalog/#server) let you send analytics data directly from your servers when client-side tracking doesn't work, or when you're sending mission-critical data like revenues.
 
-- [Analytics.js, the Segment Javascript source](/docs/connections/sources/catalog/libraries/website/javascript/), is the most powerful way to track customer data from a website. We recommend it as the default installation for any website.
-- [The Segment Mobile SDKs](/docs/connections/sources/catalog/#mobile) are the best way to simplify tracking in your iOS, Android, and Xamarin apps. We recommend them over server-side sources as the default installation for any mobile app.
-- [Server-side sources](/docs/connections/sources/catalog/#server) let you send analytics data directly from your servers when client-side tracking won't work, or when you're sending mission-critical data like revenues.
-
-We also offer other source libraries to cover less straightforward cases:
+### Sources for unique cases
+Segment also offers these other source libraries to cover less straightforward cases:
 
 - Use the [HTTP Tracking API](/docs/connections/sources/catalog/libraries/server/http-api/) if Segment doesn't offer a library for your specific environment yet.
-- The [Pixel Tracking API](/docs/connections/sources/catalog/libraries/server/pixel-tracking-api/) lets you track events from environments where you can’t execute code - for example, tracking when an email has been opened.
-- The [Querystring API](/docs/connections/sources/catalog/libraries/website/javascript/querystring/) lets you use querystrings to load API methods when a user first visits a Segment-enabled site. Use this API for tracking events like email clicks, and identifying users associated with those clicks on the destination page.
+- The [Pixel Tracking API](/docs/connections/sources/catalog/libraries/server/pixel-tracking-api/) lets you track events from environments where you can’t execute code - for example, tracking when an email was opened.
+- The [Querystring API](/docs/connections/sources/catalog/libraries/website/javascript/querystring/) lets you use querystrings to load API methods when a user first visits a Segment-enabled site. Use this API for tracking events like email clicks and identifying users associated with those clicks on the destination page.
 
+### Cloud App Sources
 Segment also offers [Cloud App Sources](/docs/connections/sources/about-cloud-sources/) to integrate data from your third-party tools:
 
-- [Object Cloud Sources](/docs/connections/sources/about-cloud-sources/#event-cloud-app-sources) can import third party tool data directly into your Segment warehouse, but cannot stream that data into your other Segment destinations. Make sure you have a Segment warehouse enabled before you enable an object cloud source.
+- [Object Cloud Sources](/docs/connections/sources/about-cloud-sources/#event-cloud-app-sources) can import third party tool data directly into your Segment warehouse, but can't stream that data into your other Segment destinations. Make sure you enable a Segment warehouse before you enable an object cloud source.
 - [Event Cloud Sources](/docs/connections/sources/about-cloud-sources/#object-cloud-app-sources) don’t just import third party tool data into your Segment warehouse, they also send event data in real-time to your other Segment destinations. You don't need to set up a data warehouse to send Event Cloud Source data to your destinations.
 
-## Where you can track
+## How you can track data
 
-Segment supports several ways to implement tracking. The two most common are to use _device-based_ or _server-based_ libraries. You can use Segment's device-based libraries, such as JavaScript, iOS, and Android, to make calls on users’ browsers or mobile devices. You can also track data with Segment's server-based libraries, such as Node, Python, PHP and so on, where the calls are triggered on your own servers and then sent to the Segment servers.
+Segment supports several ways to implement tracking. The two most common are to use _device-based_ or _server-based_ libraries. You can use Segment's device-based libraries, such as JavaScript, iOS, and Android, to make calls on users’ browsers or mobile devices. You can also track data with Segment's server-based libraries, such as Node, Python, or PHP, where the calls are triggered on your own servers and then sent to the Segment servers.
 
-When you collect data using device-based libraries, you can choose between two different connection modes: you can either use "cloud-mode", where the library sends the data directly to the Segment servers which then translate and forward it, or you can use "device-mode" where the library sends the data both directly to the Segment servers, and also to the servers for the destination tool. (Device-mode sometimes requires some [additional set-up steps](/docs/connections/sources/mobile_guide/), but can unlock rich device data.)
+When you collect data using device-based libraries, you can choose between these two different connection modes:
+* **Cloud-mode** is where the library sends the data directly to the Segment servers which then translate and forward it.
+* **Device-mode** is where the library sends the data both directly to the Segment servers, and also to the servers for the destination tool. Device-mode sometimes requires some [additional set-up steps](/docs/connections/sources/mobile_guide/), but can unlock rich device data.
 
-Although there are some tradeoffs between the two approaches, neither is better than the other, and we usually recommend that you implement a mix of both. In general, more direct interaction data is available using a device-based library, but server-based collection is more secure, reliable, and can’t be blocked by ad blockers.
+Although there are some tradeoffs between the two approaches, neither is better than the other, and Segment recommends that you implement a mix of both. In general, more direct interaction data is available using a device-based library, but server-based collection is more secure, reliable, and can’t be blocked by ad blockers.
 
 <!-- Here’s a handy flow chart to help with the client-side/server-side decision:
 
@@ -57,12 +57,12 @@ TODO: Image removed, didn't work with formatting. need a better version of this
 
 The Segment libraries generate messages about what happens on your interface, translate those messages into different formats for use by destinations, and transmit the messages to those tools.
 
-There are several [tracking API methods](/docs/connections/spec/), which can be called to generate messages. The four most important methods are:
-  - [Identify](/docs/connections/spec/identify/): who is the user?
-  - [Page](/docs/connections/spec/page/) and [Screen](/docs/connections/spec/screen/): what web page or app screen are they on?
-  - [Track](/docs/connections/spec/track/): what are they doing?
+There are several [tracking API methods](/docs/connections/spec/), that you can call to generate messages. The four most important methods are:
+  - [Identify](/docs/connections/spec/identify/): Who is the user?
+  - [Page](/docs/connections/spec/page/) and [Screen](/docs/connections/spec/screen/): What web page or app screen are they on?
+  - [Track](/docs/connections/spec/track/): What are they doing?
 
-Every call shares the same [common fields](/docs/connections/spec/common/).  When you use these methods [as intended](/docs/connections/spec/best-practices-identify/), it allows Segment to detect specific type of data, and correctly translate it to send it on to downstream destinations.
+Every call shares the same [common fields](/docs/connections/spec/common/). When you use these methods [as intended](/docs/connections/spec/best-practices-identify/), it allows Segment to detect a specific type of data and correctly translate it to send it on to downstream destinations.
 
 
 ## Where you can send data
@@ -74,14 +74,6 @@ Segment maintains a catalog of destinations where you can send your data.
 ![](images/dests_grid.png)
 
 
-
-## Workspaces
-
-Your Segment Workspace is where you set up and manage sources and destinations, manage the schema of the data your interfaces send, and test and monitor that data for errors. A Workspace is a collection of Segment sources, destinations, and their configurations, that are administered and billed together. Each Workspace has a specific list of Segment users who may access it, and it might also contain several "environments" for production, development and testing use.
-
-When you first log in to your Segment account, you can create a new workspace, or choose to log into an existing workspace if your account is part of an existing organization.
-
-
 <div class="double">
   {% include components/reference-button.html href="/getting-started/" newtab="false" newtab="false" icon="symbols/arrow-left.svg" title="Getting Started Overview" description="" variant="related" subtitle="back" %}
 

src/getting-started/index.md

@@ -4,11 +4,11 @@ title: Getting Started With Segment
 
 <iframe width="100%" height="385" src="https://www.youtube.com/embed/-5nUITqOz3Y" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
-With Segment, you can collect, transform, send, and archive your [first-party customer data](https://segment.com/books/customer-data/first-party-data/). We simplify the process of collecting data and hooking up new tools, allowing you to spend more time using your data, and less time trying to collect it. You can use Segment to track events that happen when a user interacts with the interfaces. "Interfaces" is our generic word for any digital properties you own: your website, mobile apps, and processes that run on a server or OTT device.
+With Segment, you can collect, transform, send, and archive your [first-party customer data](https://segment.com/books/customer-data/first-party-data/). Segment simplifies the process of collecting data and connecting new tools, allowing you to spend more time using your data, and less time trying to collect it. You can use Segment to track events that happen when a user interacts with the interfaces. "Interfaces" is Segment's generic word for any digital properties you own: your website, mobile apps, and processes that run on a server or OTT device.
 
-When you capture interaction data in Segment, you can send it (often in real-time) to your favorite tools marketing, product, and analytics tools, as well as to data warehouses. In most cases, you won't even need to touch your tracking code to connect new tools.
+When you capture interaction data in Segment, you can send it (often in real-time) to your marketing, product, and analytics tools, as well as to data warehouses. In most cases, you won't even need to touch your tracking code to connect to new tools.
 
 <div class="double">
   <div></div>
-  {% include components/reference-button.html newtab="false" href="/getting-started/01-what-is-segment/" icon="symbols/arrow-right.svg" title="Ready to get started?" description="We'll walk you through the steps to get up and running on Segment. Let's go!" variant="related" subtitle="next"  %}
+  {% include components/reference-button.html newtab="false" href="/getting-started/01-what-is-segment/" icon="symbols/arrow-right.svg" title="Ready to get started?" description="Let's walk through the steps to get up and running on Segment. Let's go!" variant="related" subtitle="next"  %}
 </div>