diff --git a/doc-src/SASS_CHANGELOG.md b/doc-src/SASS_CHANGELOG.md
index cba1d01049..8cf914b9e2 100644
--- a/doc-src/SASS_CHANGELOG.md
+++ b/doc-src/SASS_CHANGELOG.md
@@ -5,6 +5,16 @@
 
 ## 3.0.0.beta.2 (Unreleased)
 
+### `@warn`
+
+A new directive `@warn` has been added that allows sass libraries to emit warnings. This can be used to issue deprecation warnings, discourage sloppy coding, etc.
+`@warn` takes a single argument that is a SassScript expression that will be
+displayed on the console along with a stylesheet trace.
+
+Warnings may be silenced with the new `--quiet` command line option,
+or the corresponding `:quiet` Sass option. Warnings are off by default
+in Rails and Merb production environments.
+
 ### `sass-convert`
 
 #### `--recursive`
diff --git a/doc-src/SASS_REFERENCE.md b/doc-src/SASS_REFERENCE.md
index 56dce6f07b..2a975e5d21 100644
--- a/doc-src/SASS_REFERENCE.md
+++ b/doc-src/SASS_REFERENCE.md
@@ -287,6 +287,9 @@ Available options are:
   Currently, this just means that strings in mixin arguments
   are treated as though they were in [an `=` context](#sass-script-strings).
 
+{#quiet-option} `:quiet`
+: When set to true, causes warnings to be disabled.
+
 ## CSS Extensions
 
 ### Nested Rules
@@ -898,8 +901,7 @@ and `_colors.scss` would be imported.
 The `@debug` directive prints the value of a SassScript expression
 to the standard error output stream.
 It's useful for debugging Sass files
-that have complicated SassScript going on,
-or for printing warnings in libraries.
+that have complicated SassScript going on.
 For example:
 
     @debug 10em + 12em;
@@ -908,6 +910,20 @@ outputs:
 
     Line 1 DEBUG: 22em
 
+### `@warn`
+
+The `@warn` directive prints the value of a SassScript expression
+to the standard error output stream.
+It's useful for libraries that need to warn users of deprecations
+or recovering from minor coding mistakes. There are two major distinctions
+between `@warn` and `@debug`:
+
+1. You can turn warnings off with the `--quiet` command-line option
+   or the `:quiet` Sass option.
+2. A stylesheet trace will be printed out along with the message
+   so that the user being warned can see where they are calling from
+   their code.
+
 ## Control Directives
 
 SassScript supports basic control directives