diff --git a/examples/heapsize/README.md b/examples/heapsize/README.md
index 4c01e42..001fd6d 100644
--- a/examples/heapsize/README.md
+++ b/examples/heapsize/README.md
@@ -1,4 +1,5 @@
-A complete working implementation of a custom derive.
+A complete working Macros 1.1 implementation of a custom derive. Works on any
+Rust compiler >=1.15.0.
 
 - [`heapsize/src/lib.rs`](heapsize/src/lib.rs)
 - [`heapsize_derive/src/lib.rs`](heapsize_derive/src/lib.rs)
diff --git a/examples/heapsize2/README.md b/examples/heapsize2/README.md
index 98af9fc..100a448 100644
--- a/examples/heapsize2/README.md
+++ b/examples/heapsize2/README.md
@@ -1,2 +1,7 @@
-WIP -- a version of [`heapsize`](../heapsize) that uses `Span::def_site()` to
-resolve paths against what is in scope within the derive crate.
+A complete working custom derive that illustrates the hygiene properties of
+Macros 2.0. Currently requires a nightly Rust compiler >=1.24.0-nightly but we
+are working to stabilize all of the APIs used here.
+
+This is the same example as the unhygienic stable [`heapsize`](../heapsize)
+example. Please read that other example first before diving into this one, as
+the comments here assume an understanding of how the other one works.