Changes as per review comments

Author: reshmabidikar

userguide/aviate/aviate-catalog-guide.adoc

@@ -2,8 +2,8 @@
 
 == Introduction
 
-The http://aviate.killbill.io[Aviate Catalog UI] allows you to create individual catalog entries such as products, plans, and pricelists.
-This means you don’t need to manage entire catalog versions.
+The https://aviate.killbill.io[Aviate Catalog UI] allows you to create individual catalog entries such as products, plans, and pricelists.
+This provides much finer granularity than the Kill Bill open-source model, which requires creating a new catalog version for any change. As a result, this approach is more dynamic and scales significantly better when managing a large number of catalog entries.
 Internally, the UI uses the https://apidocs.killbill.io/aviate-catalog[Aviate Catalog APIs].
 
 == Create Product,Plan, Pricelist
@@ -53,10 +53,13 @@ Demo:
 
 API used: https://apidocs.killbill.io/aviate-catalog#create-plan[Create Plan API].
 
+[[edit_plan]]
 == Edit Plan
 
-You can update *plan prices* after creation.
-Other attributes (like phase duration) cannot be changed.
+The edit plan feature allows you to update plan prices after a plan is created. Note that Other attributes (like *phase duration*) cannot be changed.
+
+[NOTE]
+Editing a plan creates a new version of the plan. Existing subscriptions continue to use the old plan. See https://docs.killbill.io/latest/userguide_subscription#_catalog_versions[docs].
 
 . Select the plan (e.g., `netflix-basic-monthly`).
 . Adjust the price.
@@ -79,7 +82,7 @@ API used: https://apidocs.killbill.io/aviate-catalog#modify-plan[Modify Plan API
 == Archive Plan
 
 You can archive an existing plan. Archiving prevents creating new subscriptions corresponding to the plan.
-Existing subscriptions remain active.
+The plan remains active for existing subscriptions.
 
 . Select the plan (e.g., `Netflix Usage Monthly`).
 . Choose *Archive*.
@@ -102,7 +105,8 @@ API used: https://apidocs.killbill.io/aviate-catalog#retire-plan[Retire Plan API
 == Delete Plan
 
 You can delete an existing plan permanently. Deleting permanently removes a plan from the database.
-Use this only for plans created erroneously that do not have active subscriptions.
+
+WARNING: Deleting a plan could break the system if there are active subscriptions. Use this only for plans created erroneously that do not have active subscriptions.
 
 . Select the plan.
 . Choose *Delete*.
@@ -117,6 +121,10 @@ API used: https://apidocs.killbill.io/aviate-catalog#delete-plan[Delete Plan API
 
 You can create a new plan based on an existing plan.
 
+[NOTE]
+The *Duplicate Plan* feature is a time-saving convenience that lets you quickly create a new plan. When duplicating, all plan attributes can be edited and on saving,a new plan is created.
+By contrast, the <<edit_plan, Edit Plan>> feature is limited to updating prices only, and each change automatically generates a new version of the plan.
+
 . Select the plan
 . Choose *Duplicate*
 . Make changes to the plan as desired
@@ -137,9 +145,9 @@ Demo:
 
 == Creating Usage Plans
 
-Usage plans allow billing based on consumption:
+Usage plans allow billing based on consumption. See https://docs.killbill.io/latest/userguide_subscription#components-catalog-usage[docs].
 
-. Define a *billing meter* (how usage is tracked).
+. Define a https://apidocs.killbill.io/aviate-metering#billingmeter[billing meter] (how usage is tracked).
 . Configure *blocks/tiers*.
 . Assign usage-based prices to each block.
 . Save the plan.

userguide/aviate/aviate_getting_started.adoc

@@ -12,7 +12,7 @@ In this guide, you will:
 
 The example company used throughout this guide is *CloudSprout*, a fictional SaaS business operating in the UK and France.
 
----
+''''
 
 == Concepts Overview
 
@@ -27,7 +27,7 @@ In short:
 * Use *Aviate* to *set things up*.
 * Use *Kaui* to *run billing operations*.
 
----
+''''
 
 == Step 1: Start in Aviate (Get Started)
 
@@ -61,7 +61,7 @@ The following demo shows how you can configure the company settings via Aviate.
 </div>
 ++++
 
----
+''''
 
 === Configure the catalog
 
@@ -99,7 +99,7 @@ image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/avi
 
 This step only defines products and plans. No customers are created yet.
 
----
+''''
 
 === Configure taxes
 
@@ -124,7 +124,7 @@ The following demo explains how you can configure the above tax codes:
 </div>
 ++++
 
----
+''''
 
 == Step 2: Switch to Kaui (Billing Operations)
 
@@ -142,7 +142,7 @@ The following demo illustrates how you can switch to Kaui:
 </div>
 ++++
 
----
+''''
 
 === Create your first customer
 
@@ -153,7 +153,7 @@ In Kaui:
 . Select the appropriate currency (EUR or GBP).
 . Save the account.
 
----
+''''
 
 The following demo illustrates the account creation process in Kaui:
 
@@ -192,7 +192,7 @@ The following demo guides you through the subscription creation process in Kaui:
 </div>
 ++++
 
----
+''''
 
 === View the invoice
 
@@ -219,7 +219,7 @@ The following demo illustrates verifying the generated invoice:
 </div>
 ++++
 
----
+''''
 
 == What You Have Achieved
 
@@ -235,7 +235,7 @@ By following this guide, you have:
 
 You now have a fully working fictive SaaS company ready for demos or experimentation.
 
----
+''''
 
 == Next Steps