From 668592918c15157dd690ffd05f5c0f0b22b85c8d Mon Sep 17 00:00:00 2001
From: Mayur Kale <mayurkale@google.com>
Date: Tue, 26 Nov 2019 10:56:27 -0800
Subject: [PATCH] fix: review comments

---
 doc/exporter-guide.md | 37 +++++++++++++++++++++----------------
 1 file changed, 21 insertions(+), 16 deletions(-)

diff --git a/doc/exporter-guide.md b/doc/exporter-guide.md
index f4109b7fa32..6bdc31a0a51 100644
--- a/doc/exporter-guide.md
+++ b/doc/exporter-guide.md
@@ -1,18 +1,8 @@
 # Exporter Developer Guide
 
-An exporter sends traces and metrics to any backend that is capable of consuming them. The exporter itself can change without requiring a change in your client code.
+An exporter sends traces and metrics to any backend that is capable of consuming them. With OpenTelemetry, you can easily add and remove any exporter without requiring changes to your application code.
 
-OpenTelemetry exporters can be contributed by anyone, and we provide support for several open source backends and vendors out-of-the-box, example Zipkin, Jaeger, Prometheus. This document will provide a means for developers to create their own. We strongly recommended to create a dedicated package for newly added exporter, example: `@opentelemetry/exporter-myexporter`.
-
-## Tracing
-
-`SpanExporter` defines the interface that protocol-specific exporters must implement so that they can be plugged into OpenTelemetry SDK and support sending of spans data. Exporters should expect to receive only sampled-in ended spans. Exporters must not throw. Exporters should not modify spans they receive.
-
-Each exporter must implement `SpanExporter`, which contain `export` and `shutdown` methods:
-
-- `export`: Exports a batch of telemetry data. In this method you’ll process and translate `ReadableSpan` Data into the data that your trace backend accepts.
-
-- `shutdown`: Shuts down the exporter. This is an opportunity for exporter to do any cleanup required. `Shutdown` should be called only once for each Exporter instance. After the call to `Shutdown` subsequent calls to Export are not allowed and should return `FailedNotRetryable` error.
+We provide support for several open source backends and vendors out-of-the-box like Zipkin, Jaeger, and Prometheus, but OpenTelemetry exporters follow a public interface can be implemented by anyone. This document describes the process for developers to create their own exporter if the provided ones do not meet their needs.
 
 A typical package layout:
 
@@ -28,17 +18,32 @@ opentelemetry-exporter-myexporter
        └── myexporter.test.ts
 ```
 
-The queuing or batching functionalities are not needed to implemented by the exporter, it is being taken care by the `BatchSpanProcessor`.
+## Tracing
+
+The `SpanExporter` interface defines which methods the protocol-specific trace/span exporters must implement so that they can be plugged into OpenTelemetry SDK. Span exporters must follow these rules:
+
+1. Implement the `SpanExporter` interface.
+2. Expect to only receive spans which have been sampled.
+3. Expect to only receive spans which are ended.
+4. Do not throw exceptions.
+5. Do not modify received spans.
+6. Do not implement queuing or batching logic because this is handled by Span Processors.
+
+The current `SpanExporter` interface (`0.2.0`) contains 2 methods:
+
+- `export`: Exports a batch of spans. In this method, you’ll process and translate `ReadableSpan` Data into the data that your trace backend accepts, and send them to your tracing backend.
+
+- `shutdown`: Shuts down the exporter. This is an opportunity for exporter to do any cleanup required. `Shutdown` should be called only once for each Exporter instance. After the call to `Shutdown` subsequent calls to Export are not allowed and should return `FailedNotRetryable` error.
 
 Please refer to the [Zipkin Exporter][zipkin-exporter] or [Jaeger Exporter][jaeger-exporter] for more comprehensive examples.
 
 ## Metrics
 
-`MetricExporter` defines the interface that protocol-specific exporters must implement so that they can be plugged into OpenTelemetry SDK and support sending of metrics data.
+The `MetricExporter` defines the interface that protocol-specific exporters must implement so that they can be plugged into OpenTelemetry SDK and support sending of metrics data.
 
-Each exporter must implement `MetricExporter`, which contain `export` and `shutdown` methods:
+The current `MetricExporter` interface (`0.2.0`) defines 2 methods:
 
-- `export`: Exports a batch of telemetry data. In this method you’ll process and translate `ReadableMetric` Data into the data that your trace backend accepts.
+- `export`: Exports a batch of telemetry data. In this method you’ll process and translate `ReadableMetric` Data into the data that your metric backend accepts.
 
 - `shutdown`: Shuts down the exporter. This is an opportunity for exporter to do any cleanup required. `Shutdown` should be called only once for each Exporter instance. After the call to `Shutdown` subsequent calls to Export are not allowed and should return `FailedNotRetryable` error.