elastic · bmorelli25 · Jul 10, 2019 · Jul 3, 2019 · Jul 10, 2019
diff --git a/docs/guide/agent-server-compatibility.asciidoc b/docs/guide/agent-server-compatibility.asciidoc
@@ -1,79 +1,41 @@
 [[agent-server-compatibility]]
-== Agent/Server compatibility
+== Agent and Server compatibility
 
-Below is a chart that outlines the compatibility between different versions of the APM agents and the APM Server.
-
-[float]
-[[go-compatibility]]
-==== Go Agent Compatibility
-
-[options="header"]
-|=======================================================================
-|Agent Version |APM Server Version
-|1.x |>= 6.5
-|=======================================================================
-
-[float]
-[[java-compatibility]]
-==== Java Agent Compatibility
-
-[options="header"]
-|=======================================================================
-|Agent Version |APM Server Version
-|1.x |>= 6.5
-|=======================================================================
-
-[float]
-[[dotnet-compatibility]]
-==== .NET Agent Compatibility
-
-[options="header"]
-|=======================================================================
-|Agent Version |APM Server Version
-|1.0.0-beta1 |>= 6.5
-|=======================================================================
-
-[float]
-[[nodejs-compatibility]]
-==== Node.js Agent Compatibility
-
-[options="header"]
-|=======================================================================
-|Agent Version |APM Server Version
-|1.x |6.2-6.x
-|2.x |>= 6.5
-|=======================================================================
-
-[float]
-[[python-compatibility]]
-==== Python Agent Compatibility
-
-[options="header"]
-|=======================================================================
-|Agent Version |APM Server Version
-|2.x, 3.x |6.2-6.x
-|4.x |>= 6.5
-|=======================================================================
-
-[float]
-[[ruby-compatibility]]
-==== Ruby Agent Compatibility
-
-[options="header"]
-|=======================================================================
-|Agent Version |APM Server Version
-|1.x |6.4-6.x
-|2.x |>= 6.5
-|=======================================================================
-
-[float]
-[[rum-compatibility]]
-==== RUM Agent Compatibility
+The chart below outlines the compatibility between different versions of the APM agents and the APM Server.
 
 [options="header"]
-|=======================================================================
-|Agent Version |APM Server Version
-|0.x |6.3-6.4
-|1.x |6.4
-|2.x, 3.x, 4.x |>= 6.5
-|=======================================================================
+|====
+|Agent |Agent Version |APM Server Version
+// Go
+.1+|**Go Agent**
+|`1.x` |>= `6.5`
+
+// Java
+.1+|**Java Agent**
+|`1.x`|>= `6.5`
+
+// .NET
+.1+|**.NET Agent**
+|`1.0.0-beta1` |>= `6.5`
+
+// Node
+.2+|**Node.js Agent**
+|`1.x` |`6.2`-`6.x`
+|`2.x` |>= `6.5`
+
+// Python
+.2+|**Python Agent**
+|`2.x`, `3.x` |`6.2`-`6.x`
+|`4.x` |>= `6.5`
+
+// Ruby
+.2+|**Ruby Agent**
+|`1.x` |`6.4`-`6.x`
+|`2.x` |>= `6.5`
+
+// RUM
+.3+|**JavaScript RUM Agent**
+|`0.x` |`6.3`-`6.4`
+|`1.x` |`6.4`
+|`2.x`, `3.x`, `4.x` |>= `6.5`
+|====
diff --git a/docs/guide/apm-architecture.png b/docs/guide/apm-architecture.png
diff --git a/docs/guide/apm-doc-directory.asciidoc b/docs/guide/apm-doc-directory.asciidoc
@@ -1,87 +1,70 @@
-[[doc-directory]]
-== Documentation directory
+[[components]]
+== Components and documentation
 
-The following sections are designed to guide you through the available Elastic APM documentation.
+Elastic APM consists of four components: *APM Agents*, *APM Server*, *Elasticsearch*, and *Kibana*.
+
+image::images/apm-architecture-cloud.png[Architecture of Elastic APM]
 
 [float]
-=== APM Overview
+=== APM Agents
 
-You're here!
-The APM Overview is your launchpad for getting started with APM.
-We recommend reading through this documentation to gain a deeper understanding of the Elastic APM ecosystem.
+APM agents are open source libraries written in the same language as your service.
+You may only need one, or you might use all of them.
+You install them into your service as you would install any other library.
+They instrument your code and collect performance data and errors at runtime.
+This data is buffered for a short period and sent on to APM Server.
 
-* <<overview>>
-* <<install-and-run>>
-* <<apm-data-model>>
-* <<distributed-tracing>>
-* <<agent-server-compatibility>>
+Each agent has its own documentation:
 
-TIP: Want to skip straight to installation?
-Simply use an existing cluster or grab a fresh installation of the Elastic Stack,
-spin up an APM Server, and add a bit of code to instrument your app with agents.
-Full details are available on the <<install-and-run,install and run>> page.
+* {apm-go-ref-v}/introduction.html[Go agent]
+* {apm-java-ref-v}/intro.html[Java agent]
+* {apm-dotnet-ref-v}/intro.html[.NET agent]
+* {apm-node-ref-v}/intro.html[Node.js agent]
+* {apm-py-ref-v}/getting-started.html[Python agent]
+* {apm-ruby-ref-v}/introduction.html[Ruby agent]
+* {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent]
 
 [float]
 === APM Server
 
-The APM Server receives data from APM agents and converts that data into Elasticsearch documents.
+APM Server is an open source application that receives performance data from your APM agents.
+It's a {apm-server-ref-v}/why-separate-component.html[separate component by design],
+which helps keep the agents light, prevents certain security risks, and improves compatibility across the Elastic Stack.  
+
+After the APM Server has validated and processed events from the APM agents,
+the server transforms the data into Elasticsearch documents and stores them in corresponding
+{apm-server-ref-v}/exploring-es-data.html[Elasticsearch indices].
+In a matter of seconds you can start viewing your application performance data in the Kibana APM UI.
+
+// Todo: Change these links to include APM Server on Cloud installation
+// The easiest way to get started with Elastic APM is by using our
+// https://www.elastic.co/cloud/elasticsearch-service[hosted {es} Service] on
+// Elastic Cloud 
 The {apm-server-ref-v}/index.html[APM Server reference] provides everything you need when it comes to working with the server.
 Here you can learn about {apm-server-ref-v}/installing.html[installation],
 {apm-server-ref-v}/configuring-howto-apm-server.html[configuration],
 {apm-server-ref-v}/securing-apm-server.html[security],
 {apm-server-ref-v}/monitoring.html[monitoring], and more.
 
 [float]
-=== APM Agents
+=== Elasticsearch
 
-APM agents are open source libraries that you install into your services.
-You may only need one, or you might use all of them.
-Each agent has its own documentation:
-
-* {apm-go-ref}/introduction.html[Go agent]
-* {apm-java-ref}/intro.html[Java agent]
-* {apm-dotnet-ref-v}/intro.html[.NET agent]
-* {apm-node-ref}/intro.html[Node.js agent]
-* {apm-py-ref}/getting-started.html[Python agent]
-* {apm-ruby-ref}/introduction.html[Ruby agent]
-* {apm-rum-ref}/intro.html[JavaScript Real User Monitoring (RUM) agent]
+{ref}/index.html[Elasticsearch] is a highly scalable open-source full-text search and analytics engine.
+It allows you to store, search, and analyze large volumes of data quickly and in near real time.
+Elasticsearch is used to store APM performance metrics and make use of its aggregations.
 
 [float]
 === APM Kibana UI
 
-Application performance monitoring is all about visualizing data and detecting bottlenecks, so it's crucial you understand how to use the {kibana-ref}/xpack-apm.html[Kibana APM UI]. The following sections will help you get started:
+{kibana-ref}/index.html[Kibana] is an open source analytics and visualization platform designed to work with Elasticsearch.
+You use Kibana to search, view, and interact with data stored in Elasticsearch.
+
+Since application performance monitoring is all about visualizing data and detecting bottlenecks,
+it's crucial you understand how to use the {kibana-ref}/xpack-apm.html[Kibana APM UI].
+The following sections will help you get started:
 
 * {kibana-ref}/apm-getting-started.html[Getting Started]
 * {kibana-ref}/apm-bottlenecks.html[Visualizing application bottlenecks]
 * {kibana-ref}/apm-ui.html[Using the APM UI]
 
 APM also has built-in integrations with Machine Learning. To learn more about this feature, refer to the Kibana UI documentation for {kibana-ref}/machine-learning-integration.html[Machine learning integration].
-
-TIP: If you'd like to dive deeper into Kibana, the general {kibana-ref}/index.html[Kibana documentation] is also helpful.
-
-[float]
-=== Troubleshooting
-
-If you run into trouble, there are three places you can look for help:
-Troubleshooting documentation, GitHub repositories, and our discussion forum.
-
-[float]
-==== Troubleshooting documentation
-
-The APM Server and some of the APM agents have troubleshooting guides:
-
-* {apm-server-ref-v}/troubleshooting.html[Server troubleshooting]
-* {apm-java-ref}/trouble-shooting.html[Java agent troubleshooting]
-* {apm-node-ref}/troubleshooting.html[Node.js agent troubleshooting]
-* {apm-rum-ref}/troubleshooting.html[RUM troubleshooting]
-
-[float]
-==== GitHub repositories
-
-Elastic APM is open source! Our https://github.com/elastic?utf8=%E2%9C%93&q=apm[GitHub repositories] have a plethora of knowledge available in the form of code, issues, and PRs.
-
-[float]
-==== Discussion forum
-
-For additional questions and feature requests,
-visit our https://discuss.elastic.co/c/apm[discussion forum].
diff --git a/docs/guide/apm-release-notes.asciidoc b/docs/guide/apm-release-notes.asciidoc
@@ -40,7 +40,7 @@ The Geo-IP pipeline takes an extracted IP address from RUM events and stores it
 This makes it much easier to use location data in Kibana's Visualize maps and Maps app directly:
 
 [role="screenshot"]
-image::kibana-geo-data.png[Kibana maps app]
+image::images/kibana-geo-data.png[Kibana maps app]
 
 *APM UI*
 

diff --git a/docs/guide/distributed-tracing.asciidoc b/docs/guide/distributed-tracing.asciidoc
@@ -1,6 +1,9 @@
 [[distributed-tracing]]
 == Distributed tracing
 
+Together, <<transactions,`Transactions`>> and <<transaction-spans,`Spans`>> form a `Trace`.
+Traces are not events, but group together events that have a common root.
+
 Elastic APM supports distributed tracing.
 Distributed tracing enables you to analyze performance throughout your microservices architecture all in one view.
 This is accomplished by tracing all of the requests - from the initial web request to your front-end service - to queries made to your back-end services.
@@ -11,4 +14,4 @@ The APM UI in Kibana also supports distributed tracing.
 The Timeline visualization has been redesigned to show all of the transactions from individual services that are connected in a trace:
 
 [role="screenshot"]
-image::distributed-tracing.jpg[distribute tracing in the UI]
+image::images/apm-distributed-tracing.png[Distributed tracing in the APM UI]
diff --git a/docs/guide/distributed-tracing.jpg b/docs/guide/distributed-tracing.jpg
diff --git a/docs/guide/images/apm-architecture-cloud.png b/docs/guide/images/apm-architecture-cloud.png
diff --git a/docs/guide/images/apm-architecture-diy.png b/docs/guide/images/apm-architecture-diy.png
diff --git a/docs/guide/images/apm-distributed-tracing.png b/docs/guide/images/apm-distributed-tracing.png
diff --git a/docs/guide/kibana-geo-data.png → docs/guide/images/kibana-geo-data.png b/docs/guide/kibana-geo-data.png → docs/guide/images/kibana-geo-data.png
diff --git a/docs/guide/index.asciidoc b/docs/guide/index.asciidoc
@@ -9,22 +9,26 @@ endif::[]
 [[gettting-started]]
 = APM Overview
 
-include::./apm-doc-directory.asciidoc[]
-
 include::./overview.asciidoc[]
 
+include::./apm-doc-directory.asciidoc[]
+
 include::./install-and-run.asciidoc[]
 
 include::./apm-data-model.asciidoc[]
 
 include::./distributed-tracing.asciidoc[]
 
+include::./rum.asciidoc[]
+
 include::./opentracing.asciidoc[]
 
 include::./agent-server-compatibility.asciidoc[]
 
+include::./troubleshooting.asciidoc[]
+
 include::./apm-breaking-changes.asciidoc[]
 
 include::./apm-release-notes.asciidoc[]
 
-include::./redirects.asciidoc[]
+include::./redirects.asciidoc[]