diff --git a/README.md b/README.md
index 375d1623..7def33d8 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,11 @@
 This library is a work in progress, and as such it does not yet implement all
 functionality. It can create basic VST plugins without an editor interface.
 
+**Note:** If you are upgrading from a version prior to 0.2.0, you will need to update
+your plugin code to be compatible with the new, thread-safe plugin API. See the
+[`transfer_and_smooth`](examples/transfer_and_smooth.rs) example for a guide on how
+to port your plugin.
+
 ## Library Documentation
   - https://rustaudio.github.io/vst-rs/vst/
 
diff --git a/src/lib.rs b/src/lib.rs
index d7df8772..b6109c3a 100755
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -22,6 +22,10 @@
 //! methods concurrently with audio processing, it needs to be separate from the main `Plugin`
 //! trait.
 //!
+//! To support parameters, a plugin must provide an implementation of the `PluginParameters`
+//! trait, wrap it in an `Arc` (so it can be accessed from both threads) and
+//! return a reference to it from the `get_parameter_object` method in the `Plugin`.
+//!
 //! ## `plugin_main!` macro
 //! `plugin_main!` will export the necessary functions to create a proper VST plugin. This must be
 //! called with your VST plugin struct name in order for the vst to work.