metering: Update doc to clarify use of metering APIs

Author: sbrossie

userguide/aviate/aviate-metering.adoc

@@ -4,9 +4,9 @@ include::{sourcedir}/aviate/includes/aviate-card.adoc[]
 
 == Introduction
 
-The Aviate plugin offers metering capabilities. The https://apidocs.killbill.io/usage[Kill Bill core usage APIs] support recording rolled-up usage data. However, any required aggregation must be performed outside Kill Bill. With the introduction of the metering feature, aggregation can now occur directly within Kill Bill. Thus, this feature allows users to be charged based on aggregated units seamlessly.
+The Aviate plugin offers metering capabilities. The https://apidocs.killbill.io/usage[Kill Bill core usage APIs] support recording rolled-up usage data, but aggregation must be performed outside Kill Bill. With the introduction of the metering feature, aggregation can now occur directly within Kill Bill by using the metering APIs. Thus, this feature allows users to be charged based on aggregated units seamlessly.
 
-The Aviate Metering feature introduces the concept of a https://killbill.github.io/slate/aviate-metering-apis.html#billingmeter[BillingMeter] and a https://killbill.github.io/slate/aviate-metering-apis.html#usageevent[UsageEvent]. A `BillingMeter` encapsulates information about how usages should be aggregated. A `UsageEvent` represents a single usage. Each `UsageEvent` has an associated `BillingMeter`. The `UsageEvents` are then aggregated based on the aggregation type specified in the associated `BillingMeter`.
+The Aviate Metering feature introduces the concept of a https://killbill.github.io/slate/aviate-metering-apis.html#billingmeter[BillingMeter] and a https://killbill.github.io/slate/aviate-metering-apis.html#usageevent[UsageEvent]. A `BillingMeter` encapsulates information about how usage points should be aggregated - e.g. sum all points within a specific period. A `UsageEvent` represents a single usage point. Each `UsageEvent` has an associated `BillingMeter`. The `UsageEvents` are then aggregated based on the aggregation type specified in the associated `BillingMeter`.
 
 == Getting Started with Aviate Metering
 
@@ -29,11 +29,13 @@ Refer to the https://docs.killbill.io/latest/userguide_configuration.html[__Kill
 
 === Using Metering APIs
 
-Once the aviate plugin is installed and the metering feature is enabled, you can start using the Aviate Metering APIs. These APIs enable creation of billing meters and usage recording. They are documented in our https://apidocs.killbill.io/aviate-metering[api docs].
+Once the aviate plugin has been installed and the metering feature is enabled, you can start using the Aviate Metering APIs. These APIs enable creation of billing meters and allow to record raw (non aggregated) usage points. These APIs replace the https://killbill.github.io/slate/usage.html#record-usage-for-a-subscription[Kill Bill usage APIs]: Users should either use existing Kill Bill usage APIs (to record aggregated usage points) or use the Aviate metering APIs discussed in this section. For more details about these APIs, please refer to our https://apidocs.killbill.io/aviate-metering[api docs].
+
+Note that in the current implementation, the caller should ensure that all usage points for a specific subscription should be serialized.
 
 == A Metering Example
 
-This section explains how metering works with an example.
+This section explains how metering works with an example. We also provide a https://docs.killbill.io/latest/aviate-usage-ai-tutorial[tutorial] with step by step examples. 
 
 Assume that we would like to track the cellphone minutes consumed by a user. We can create a `BillingMeter` as follows: