[docs] Prepare docs

docs/configuration.asciidoc

@@ -0,0 +1,129 @@
+////
+Goal of this doc:
+Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.)
+
+Assumptions we're comfortable making about the reader:
+* They are familiar with Elastic
+* They are familiar with OpenTelemetry
+////
+
+[[configuration]]
+== Configure
+
+:language: Java
+:language_lc: java
+:distro_name: Elastic Distribution for OpenTelemetry {language}
+
+include::release-status.asciidoc[]
+
+////
+How do users set configuration options?
+////
+[discrete]
+[[configure-methods]]
+=== Configuration methods
+
+////
+Are there multiple ways to set configuration options?
+For example, can they use environment variables OR a config file?
+If there are, what are they and why would you use each method?
+Where/how do you use each method?
+Provide an example to illustrate the syntax.
+////
+
+////
+If configuration options are defined using multiple methods, which one takes precedence over the other(s)?
+////
+
+[discrete]
+[[configuration-options]]
+=== Configuration options
+
+////
+Is this true? Is the distro a wrapper around the OpenTelemetry Java agent
+which is a wrapper around the general OpenTelemetry SDK? 🌀
+////
+Because the Elastic Distribution for OpenTelemetry Java (the distro) is a wrapper around the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java agent], it supports both:
+
+* General OpenTelemetry SDK configuration options
+* Elastic-specific configuration options that are only available when using the distro
+
+[discrete]
+[[configure-otel-sdk-options]]
+==== OpenTelemetry SDK configuration options
+
+////
+Is this true?
+Are there any options that aren't supported?
+Any options that shouldn't be used?
+////
+The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation].
+
+////
+Are there Elastic-specific custom configuration options
+in addition to the general OpenTelemetry SDK
+configuration options? Or are all the customizations
+"behind the scenes"?
+If not, you can delete this section.
+////
+[discrete]
+[[configure-distro-options]]
+==== Elastic-specific configuration options
+
+The distro supports the following Elastic-specific options:
+
+////
+List config options
+////
+
+////
+Are there multiple authentication methods when sending data to Elastic?
+If not, delete this section.
+////
+[discrete]
+[[configure-auth-methods]]
+=== Authentication methods
+
+When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key.
+
+[discrete]
+[[configure-secret-token]]
+==== Use a secret token
+
+// What is this?
+// ??
+
+// Why would you choose this method?
+// ??
+
+// How do you authenticate using this method?
+// ??
+
+[discrete]
+[[configure-api-key]]
+==== Use an APM agent key (API key)
+
+// What is this?
+It is also possible to authenticate to an Elastic Observability endpoint using
+an _APM agent key_. These are revocable API keys.
+
+// Why would you choose this method?
+// ??
+
+// How do you authenticate using this method?
+To create and manage APM Agent keys in Kibana:
+
+. Go to *APM Settings*.
+. Select the *Agent Keys* tab.
+
+When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a
+different auth schema (`ApiKey` rather than `Bearer`). For example:
+
+////
+Code example
+////
+
+
+:!language:
+:!language_lc:
+:!distro_name:

docs/configure.asciidoc

@@ -1,5 +1,28 @@
+////
+I'm confused about the goal of this doc.
+
+With a title like "Configure" I expected to see a list of the
+valid configuration options. Instead it seems to be a list of
+APM Java agent configuration options, and how to update them
+to migrate from the agent to the distro.
+
+Is the intention of this doc to be a migration guide from the APM Java
+agent to the Elastic Distribution for OpenTelemetry Java?
+////
+
 [[configure]]
-== Configure
+== Migrate?
+
+// I'll add this to the automation if we're sure we want this on every page.
+:language: Java
+:language_lc: java
+:distro_name: Elastic Distribution for OpenTelemetry {language}
+
+include::release-status.asciidoc[]
+
+:!language:
+:!language_lc:
+:!distro_name:
 
 ////
 This file is auto generated. Please only make changes in `configure.asciidoc.ftl`

docs/get-started.asciidoc

@@ -1,23 +1,170 @@
+////
+Goal of this doc:
+The user is able to successfully see data from their Java application make it to the Elastic UI via the Elastic Distribution for OpenTelemetry Java
+
+Assumptions we're comfortable making about the reader:
+* They are familiar with Elastic
+* They are familiar with OpenTelemetry
+* They have Java installed
+////
+
 [[get-started]]
 == Get started
 
-This guide shows you how to use the Elastic Distribution for OpenTelemetry Java to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment.
+:language: Java
+:language_lc: java
+:distro_name: Elastic Distribution for OpenTelemetry {language}
+
+include::release-status.asciidoc[]
+
+This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment.
+
+////
+Is this true?
+////
+[NOTE]
+====
+As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (for example, an https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]).
+====
 
+////
+What does a user need to know and/or do before they install the distro?
+////
+[discrete]
+[[get-started-prerequisites]]
+=== Prerequisites
+
+Before getting started:
+
+// Familiarity with OpenTelemetry
+* *Familiarize yourself with the OpenTelemetry SDK.* The distro is a lightweight wrapper around the OpenTelemetry SDK. You should be broadly familiar with the OpenTelemetry SDK concepts and instrumenting applications using the Microsoft diagnostic APIs. If you are not familiar with this, start with the https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation].
++
+* *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one.
++
+[[elastic-observability-setup]]
+[%collapsible]
+.*Expand for setup instructions*
+====
+This section shows how to create an https://www.elastic.co/observability[Elastic Observability] cloud deployment and get the data you need to configure the distro to send data to it.
+
+. Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**.
+. After registering, click *Create deployment* at `<https://cloud.elastic.co/home>`.
+. Once that is created, click *Open* to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`.
+====
+
+////
+// Other examples of prereqs:
+// Any dependencies (including specific supported Java versions)?
+////
+
+////
+How does a user install the distro?
+////
 [discrete]
 [[get-started-install]]
 === Install
 
-. Download the latest release https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest[here].
-. Run the distro by using the `-javaagent:` JVM argument with the path to the distro jar:
+////
+Step-by-step instructions
+////
+To get started with the distro:
+
+. Download the https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest[latest release].
+. Run the distro using the `-javaagent:` JVM argument with the path to the distro jar:
 +
 [source,bash]
 ----
 java -javaagent:/path/to/agent.jar \
 -jar myapp.jar
 ----
 
+////
+Any additional info related to installation
+////
+[NOTE]
+.The Elastic distro and the OpenTelemetry SDK
+====
+The distro includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the
+OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must
+be defined _before_ the {distro_name} is defined.
+====
+
+////
+What does the user need to do in their application to prepare to send data to Elastic?
+////
+[discrete]
+[[get-started-send-data]]
+=== Send data to Elastic
+
+After installing the distro, configure and initialize it to start
+sending data to Elastic.
+
+////
+Are there any dependencies that need to be installed in addition to the distro?
+If yes, does it matter in what order dependencies are defined?
+If no, delete this section.
+////
+[discrete]
+[[get-started-add-dependencies]]
+==== Add dependencies
+
+////
+Step-by-step instructions
+////
+
+////
+What does the _minimal_ configuration / setup look like?
+Are there any configuration options that are _required_?
+////
 [discrete]
 [[get-started-configure]]
-=== Configure
+==== Configure the distro
+
+////
+Step-by-step instructions
+////
+
+////
+Does the user need to do something after configuring the distro
+for data to start being sent Elastic?
+If no, delete this section.
+////
+[discrete]
+[[get-started-initialization]]
+==== Initialize the distro
+
+////
+Step-by-step instructions
+////
+
+////
+Optional: Add an image
+////
+
+////
+What should they expect to see after running this?
+How do they know it worked as expected?
+////
+[discrete]
+[[get-started-view-traces]]
+=== View traces
+
+To view the traces, you can use the Elastic APM UI:
+
+////
+Step-by-step instructions
+////
+
+////
+What should they do next?
+////
+[discrete]
+[[get-started-next-steps]]
+=== Next steps
+
+* <<configuration,Configure the distro>> to send data to Elastic.
+* Learn more about viewing and interpreting data in the {observability-guide}/apm.html[Observability guide].
 
-See <<configure>>.
+:!language:
+:!language_lc:
+:!distro_name:

docs/index.asciidoc

@@ -3,13 +3,14 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
 ifdef::env-github[]
 NOTE: For the best reading experience,
-please view this documentation at https://www.elastic.co/guide/en/apm/agent/java[elastic.co]
+please view this documentation at https://www.elastic.co/guide/en/apm/open-telemetry/java[elastic.co]
 endif::[]
 
 = Elastic Distribution for OpenTelemetry Java
 
 ifndef::env-github[]
-include::./landing-page.asciidoc[]
+include::./intro.asciidoc[]
 include::./get-started.asciidoc[]
+include::./configuration.asciidoc[]
 include::./configure.asciidoc[]
 endif::[]