Add note about stability and tweak index docs

sdk/dotnet/Image.cs

@@ -15,16 +15,10 @@ namespace Pulumi.DockerBuild
     /// 
     /// ## Stability
     /// 
-    /// **This resource is experimental and subject to change.**
+    /// **This resource is pre-1.0 and in public preview.**
     /// 
-    /// API types are unstable. Subsequent releases _may_ require manual edits
-    /// to your state file(s) in order to adopt API changes.
-    /// 
-    /// `retainOnDelete: true` is recommended with this resource until it is
-    /// stable. This enables future API changes to be adopted more easily by renaming
-    /// resources.
-    /// 
-    /// Only use this resource if you understand and accept the risks.
+    /// We will strive to keep APIs and behavior as stable as possible, but we
+    /// cannot guarantee stability until version 1.0.
     /// 
     /// ## Migrating v3 and v4 Image resources
     /// 

sdk/dotnet/Index.cs

@@ -10,13 +10,25 @@ using Pulumi.Serialization;
 namespace Pulumi.DockerBuild
 {
     /// <summary>
-    /// An index (or manifest list) referencing one or more existing images.
+    /// A wrapper around `docker buildx imagetools create` to create an index
+    /// (or manifest list) referencing one or more existing images.
     /// 
-    /// Useful for crafting a multi-platform image from several
-    /// platform-specific images.
+    /// In most cases you do not need an `Index` to build a multi-platform
+    /// image -- specifying multiple platforms on the `Image` will handle this
+    /// for you automatically.
     /// 
-    /// This creates an OCI image index or a Docker manifest list depending on
-    /// the media types of the source images.
+    /// However, as of April 2024, building multi-platform images _with
+    /// caching_ will only export a cache for one platform at a time (see [this
+    /// discussion](https://github.com/docker/buildx/discussions/1382) for more
+    /// details).
+    /// 
+    /// Therefore this resource can be helpful if you are building
+    /// multi-platform images with caching: each platform can be built and
+    /// cached separately, and an `Index` can join them all together. An
+    /// example of this is shown below.
+    /// 
+    /// This resource creates an OCI image index or a Docker manifest list
+    /// depending on the media types of the source images.
     /// 
     /// ## Example Usage
     /// ### Multi-platform registry caching