diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index 6a8bababe4..3e22bd8d11 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -1014,13 +1014,13 @@ class Formula
     @prefix_returns_versioned_prefix = false
   end
 
-  # Tell the user about any Homebrew-specific caveats or locations regarding
-  # this package. These should not contain setup instructions that would apply
-  # to installation through a different package manager on a different OS.
+  # Warn the user about any Homebrew-specific issues or quirks for this package
+  # These should not contain setup instructions that would apply to installation
+  # through a different package manager on a different OS.
   # @return [String]
   # <pre>def caveats
   #   <<~EOS
-  #     Are optional. Something the user should know?
+  #     Are optional. Something the user must be warned about?
   #   EOS
   # end</pre>
   #
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index f706881000..c80b398ffc 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -283,6 +283,18 @@ Homebrew expects to find manual pages in `#{prefix}/share/man/...`, and not in `
 
 Some software installs to `man` instead of `share/man`, so check the output and add a `"--mandir=#{man}"` to the `./configure` line if needed.
 
+### Caveats
+
+In case there are specific issues with the Homebrew packaging (compared to how the software is installed from other sources) a `caveats` block can be added to the formula to warn users. This can indicate non-standard install paths, an example from the `ruby` formula:
+
+```
+==> Caveats
+By default, binaries installed by gem will be placed into:
+  /usr/local/lib/ruby/gems/bin
+
+You may want to add this to your PATH.
+```
+
 ### A quick word on naming
 
 Name the formula like the project markets the product. So it’s `pkg-config`, not `pkgconfig`; `sdl_mixer`, not `sdl-mixer` or `sdlmixer`.