diff --git a/docs/logging.md b/docs/logging.md
index 3bfba41..42c895f 100644
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -67,6 +67,22 @@ run the 'run' files in the ./ and ./log directories. Any log entries
 emitted will get handled per the instructions in log/run. The default
 location specified in log/run is log/main/current.
 
+## logging via 'warn'
+
+Any warnings emitted are sent to logging plugins with a deafult log level of
+LOGWARN.  Warnings can be sent to plugins with a different log level using a
+prefix.  For example:
+
+`warn 'NOTICE: Danger Will Robinson!'`
+
+Emitting this warning in a plugin is equivalent to using log():
+
+`$self->log(LOGNOTICE, 'Danger Will Robinson!')`
+
+Notably, using 'warn' in a plugin will always result in that warning being
+emitted to STDERR, wheras messages sent with log() are not output to the
+terminal when running the test suite.
+
 ## plugin loglevel
 
 Most plugins support a loglevel argument after their config/plugins entry.