diff --git a/example/ticker.cpp b/example/ticker.cpp
index 3e8f6f8..582fdf3 100644
--- a/example/ticker.cpp
+++ b/example/ticker.cpp
@@ -100,6 +100,13 @@ int main(int argc, char* argv[])
     uint32_t count = 0u;
 
     while(!done.wait(delay)) {
+        // The value that will be given to post() must come from the same type
+        // _instance_ as the initial value used when calling open(). In other
+        // words, doing
+        //     auto val = nt::NTScalar{TypeCode::UInt32}.create();
+        // won't work because it creates a different NTScalar instance. Either
+        // keep reusing the same Value, clone the existing Value, or keep aroud
+        // the type instance and create values from there.
         auto val = initial.cloneEmpty();
 
         val["value"] = count++;
diff --git a/src/pvxs/sharedpv.h b/src/pvxs/sharedpv.h
index 95e69a7..416efd3 100644
--- a/src/pvxs/sharedpv.h
+++ b/src/pvxs/sharedpv.h
@@ -71,8 +71,14 @@ struct PVXS_API SharedPV
     //! Reverse the effects of open() and force disconnect any remaining clients.
     void close();
 
-    //! Update the internal data value, and dispatch subscription updates to any clients.
+    /** Update the internal data value, and dispatch subscription updates to any clients.
+     *
+     * The value given as the argument must be created from the same `TypeDef`
+     * instance as the value given to `SharedPV::open()`. It is recommended that
+     * the same value (or its clone) is reused.
+     */
     void post(const Value& val);
+
     //! query the internal data value and update the provided Value.
     void fetch(Value& val) const;
     //! Return a (shallow) copy of the internal data value