Merge pull request #3584 from TovaCohen/FUSEDOC-2696-peerReviewUpdates

user doc: Updates resulting from peer review of first chapter in user guide

doc/integrating_applications/master.adoc

@@ -17,7 +17,8 @@ This guide provides information and instructions for using
 
 The content in this guide is organized as follows:
 
-* <<understanding>>
+* <<high-level-overview>>
+* <<how-to-get-ready>>
 * <<logging-in-and-out>>
 * <<connecting-to-applications>>
 * <<creating-integrations>>
@@ -28,7 +29,9 @@ The content in this guide is organized as follows:
 To learn how to use {prodname} by creating sample integrations, see:
 {LinkFuseOnlineTutorials}[{NameOfFuseOnlineTutorials}].
 
-include::topics/understanding.adoc[leveloffset=+1]
+include::topics/high_level_overview.adoc[leveloffset=+1]
+
+include::topics/how_to_get_ready.adoc[leveloffset=+1]
 
 include::topics/shared/log_in.adoc[leveloffset=+1]
 

doc/integrating_applications/topics/about_actions.adoc

@@ -10,4 +10,4 @@ creating a Salesforce account, updating a Salesforce account, and
 searching Salesforce.
 
 Some actions require additional configuration and {prodname}
-prompts you for this information if it is needed.
+prompts you for this information.

doc/integrating_applications/topics/about_connectors.adoc

@@ -9,11 +9,12 @@ Salesforce connector to create a connection to
 Salesforce.
 
 An application that you want to connect to might use the OAuth protocol
-to authenticate users. In this case, you register {prodname} as a client
-that can access that application. The registration is associated with the
-connector. You need to register {prodname} only once with each 
+to authenticate users. In this case, you register your {prodname} environment 
+as a client that can access that application. The registration is associated with the
+connector for that application. You need to register a particular {prodname} 
+environment only once with each 
 application that uses OAuth. The registration extends to each 
 connection that you create from that connector. 
 
 If {prodname} does not provide a connector you need, a developer
-can create the needed connector.
+can create the required connector.

doc/integrating_applications/topics/about_integrations.adoc

@@ -1,12 +1,12 @@
 [id='about-integrations']
 = About integrations
 
-To set up data integration between applications, you create an integration.
-An integration is set of ordered steps. This set includes:
+An integration is a set of ordered steps that {prodname} executes. 
+This set includes:
 
 * A step that connects to an application to start the integration. This
-connection provides the initial source data that the integration
-operates on. A subsequent connection can provide additional source data. 
+connection provides the initial data that the integration
+operates on. A subsequent connection can provide additional data. 
 
 * A step that connects to an application to complete the integration. This
 connection receives any data that was output from previous steps 
@@ -18,7 +18,7 @@ connections. Depending on the position of the additional connection
 in the sequence of integration steps, an additional connection can
 do any or all of the following:
 +
-** Provide additional source data for the integration to operate on
+** Provide additional data for the integration to operate on
 ** Process the integration data
 ** Output processing results to the integration
 

doc/integrating_applications/topics/about_steps.adoc

@@ -1,5 +1,5 @@
 [id='about-steps']
-= About steps
+= About integration steps
 
 An integration is a set of ordered steps. Each step operates on data.
 Some steps operate on data while connected to an application or service

doc/integrating_applications/topics/benefits.adoc

@@ -1,7 +1,7 @@
 [id='benefits']
-= Benefits of {prodname}
+= Benefits of using {prodname}
 
-With {prodname}, you can:
+{prodname} has a number of benefits: 
 
 * Integrate data from different applications or services without writing code.
 

doc/integrating_applications/topics/high_level_overview.adoc

@@ -0,0 +1,22 @@
+[id='high-level-overview']
+= High level overview of {prodname}
+
+With {prodname}, you can obtain data from an
+application or service, operate on that data if you need to, and then
+send the data to a completely different application or service.  No coding is
+required to accomplish this.
+
+The following topics provide a high-level overview of {prodname}:
+
+* <<how-it-works>>
+* <<audience>>
+* <<benefits>>
+* <<understanding-terms>>
+
+include::how_it_works.adoc[leveloffset=+1]
+
+include::user_types.adoc[leveloffset=+1]
+
+include::benefits.adoc[leveloffset=+1]
+
+include::term_definitions.adoc[leveloffset=+1]

doc/integrating_applications/topics/how_it_works.adoc

@@ -1,19 +1,20 @@
 [id='how-it-works']
 = How {prodname} works
 
-{prodname} lets you enable data transfer between different applications. For example,
-each time a customer is mentioned in Twitter, you might want to capture that
-mention in your Salesforce account for that customer. Another example is a service
-that makes stock trade recommendations. You can capture recommendations of interest
-and forward them to a service that automates stock transfers.
-
 {prodname} provides a web browser interface that lets you integrate two or
 more different applications or services without writing code. It also provides
 features that allow you to introduce code if it is needed for complex
 use cases.
 
-To create and run a simple integration,
-the main steps are:
+{prodname} lets you enable data transfer between different applications. 
+For example, a business analyst can use {prodname} to capture 
+tweets that mention customers and then leverage the data obtained from 
+Twitter to update Salesforce accounts. Another example is a service
+that makes stock trade recommendations. You can use {prodname} to 
+capture recommendations for buying or selling stocks of interest
+and forward those recommendations to a service that automates stock transfers.
+
+To create and run a simple integration, the main steps are:
 
 . Create a connection to each application that you want to integrate.
 . Select the start connection. This connection is to the application that
@@ -27,4 +28,4 @@ finish connection.
 . Click *Publish* to start running the integration.
 
 The {prodname} dashboard lets you monitor and manage integrations. You can
-see which integrations are running, start, stop, and edit integrations.
+see which integrations are running, and you can start, stop, and edit integrations.

doc/integrating_applications/topics/how_to_get_ready.adoc

@@ -0,0 +1,17 @@
+[id='how-to-get-ready']
+= How to get ready to create integrations
+
+Some planning and an understanding of the workflow for creating an 
+integration can help you create integrations that meet your needs. 
+The following topics provide information for getting ready to create 
+integrations. 
+
+* <<planning>>
+* <<workflow-overview>>
+* <<how-you-use>>
+
+include::planning_integrations.adoc[leveloffset=+1]
+
+include::workflow_overview.adoc[leveloffset=+1]
+
+include::how_you_use.adoc[leveloffset=+1]

doc/integrating_applications/topics/how_you_use.adoc

@@ -1,15 +1,15 @@
 [id='how-you-use']
-= How you use {prodname}
+= Example workflow for creating a Salesforce to database integration
+
+The best way to understand the workflow for using {prodname} is to 
+create the sample integrations by following the instructions in the
+{LinkFuseOnlineTutorials}[sample integration tutorials]. If you have
+already done that, you can skip this section. 
 
-The best way to learn about how to use {prodname} is to create the sample
-integrations by following the instructions in the
-{LinkFuseOnlineTutorials}[sample integration tutorials].
 The following abbreviated description of one of the samples provides
-an overview of how you use {prodname}. These steps omit details so
+an example workflow for using {prodname}. These steps omit details, so
 you should not try to follow them.
 
-NOTE: If you already created a sample integration then you can skip this section.
-
 . Register your installation of {prodname} as an application that can access
 Salesforce. You need to do this only once to be able to create any number of
 integrations that connect to Salesforce.

doc/integrating_applications/topics/planning_integrations.adoc

@@ -1,8 +1,7 @@
 [id='planning']
 = Planning integrations
 
-Some planning so that you have answers to the following questions is
-helpful before you create an integration.
+Consider the following questions before you create an integration.
 
 To start the integration:
 

doc/integrating_applications/topics/term_definitions.adoc

@@ -1,10 +1,10 @@
 [id='understanding-terms']
-= Understanding {prodname} terms
+= Descriptions of {prodname} constructs
 
-When you integrate applications with {prodname}, you create an
+To use {prodname}, you create an
 integration by working with connectors,
-connections, actions, and steps. See the following sections to
-learn about each of these constructs.
+connections, actions, and steps. The following sections describe
+these constructs.
 
 * <<about-integrations>>
 * <<about-connectors>>

doc/integrating_applications/topics/user_types.adoc

@@ -7,3 +7,20 @@ marketing, who do not want to write code in order
 to share data between two different applications. Their use of a
 variety of software-as-a-service (SaaS) applications gives them an
 understanding of business requirements, workflows, and relevant data.
+
+As a business user, you can use {prodname} to:
+
+* Capture tweets that mention your company, filter them, and create new
+contacts in your Salesforce environment when the tweet is from an unknown
+source.  
+
+* Identify Salesforce lead updates and then execute a SQL stored procedure
+to keep your related database up to date. 
+
+* Subscribe for orders received by an AMQ broker and then operate on 
+those orders with a custom API. 
+
+* Obtain data from an Amazon S3 bucket and add it to a Dropbox folder. 
+
+These are just a few examples of what a business user can do without
+writing code. 

doc/integrating_applications/topics/workflow_overview.adoc

@@ -1,5 +1,5 @@
 [id='workflow-overview']
-= Workflow for creating an integration
+= General workflow for creating an integration
 
 After you log in to the {prodname} console, the general steps
 for integrating applications are:
@@ -22,9 +22,10 @@ application that uses the data from the start connection.
 details.
 .. Optionally, between the start connection and the finish connection,
 add one or more connections to other applications.
+.. Add a data mapping step between connections that have different
+field names for the same data. Typical integrations require some
+data mapping. 
 .. Optionally, between connections, add additional steps,
-such as filtering data, mapping data fields, or
-logging that is in addition to the automatically-provided logging.
-Typical integrations require data mapping.
+such as filtering data or logging that is in addition to the automatically-provided logging.
 
 . Click *Publish* to start running your integration.