Index: sbin/swapon/swapon.8
===================================================================
--- sbin/swapon/swapon.8
+++ sbin/swapon/swapon.8
@@ -203,6 +203,16 @@
 overridden.
 512 byte blocks are used by default.
 .El
+.Sh NOTE
+ZVOL devices and ZFS swap files are discouraged for using as swap space.
+ZFS needs to allocate memory to write to swap space
+while the system is under low memory pressure trying to make some
+memory available.
+In order words, ZFS needs memory to make memory available.
+OOM killer may start killing processes as ZFS does not write to swap
+space fast enough or to allocate memory for ZFS to write to swap
+although large swap space is still available.
+.El
 .Sh FILES
 .Bl -tag -width ".Pa /dev/{ada,da}?s?b" -compact
 .It Pa /dev/{ada,da}?s?b