diff --git a/src/core/types.ml b/src/core/types.ml
index 87dd6b4..a37127f 100644
--- a/src/core/types.ml
+++ b/src/core/types.ml
@@ -1,7 +1,9 @@
 (** Main type definitions *)
 
 type span = ..
-(** A span. Its representation is defined by the current collector. *)
+(** A span. Its representation is defined by the current collector.
+
+    This representation changed in 0.11 (from [int64] to an open sum type) *)
 
 (** Information about a span's parent span, if any.
     @since 0.11 *)
diff --git a/src/tls/trace_thread_local_storage.mli b/src/tls/trace_thread_local_storage.mli
index e0bae7b..d89cfa4 100644
--- a/src/tls/trace_thread_local_storage.mli
+++ b/src/tls/trace_thread_local_storage.mli
@@ -1,7 +1,9 @@
 (** use [thread-local-storage] to store ambient spans.
 
     This doesn't work with cooperative concurrency (Eio, Lwt, etc) but is fine
-    in a threaded context. *)
+    in a threaded context.
+
+    @since 0.12 *)
 
 open Trace_core
 
@@ -9,6 +11,9 @@ val k_span : span Thread_local_storage.t
 (** Key to access the current span *)
 
 val provider : Ambient_span_provider.t
+(** Provider that uses [Thread_local_storage] to store the current ambient span.
+    This works well when concurrency is based on thread, or if there is no
+    concurrency. *)
 
 val setup : unit -> unit
 (** Install the provider *)