diff --git a/docs/changelog.txt b/docs/changelog.txt
index fef273c64..7313f6f8a 100644
--- a/docs/changelog.txt
+++ b/docs/changelog.txt
@@ -43,6 +43,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - ``widgets.EditField``: DFHack edit fields now support cut/copy/paste with the system clipboard with Ctrl-X/Ctrl-C/Ctrl-V
 
 ## Documentation
+- `misery`: rewrite the documentation to clarify the actual effects of the plugin
 
 ## API
 - ``Units::getUnitByNobleRole``, ``Units::getUnitsByNobleRole``: unit lookup API by role
diff --git a/docs/plugins/misery.rst b/docs/plugins/misery.rst
index 8a65d8419..458253bb5 100644
--- a/docs/plugins/misery.rst
+++ b/docs/plugins/misery.rst
@@ -2,11 +2,12 @@ misery
 ======
 
 .. dfhack-tool::
-    :summary: Increase the intensity of your citizens' negative thoughts.
+    :summary: Lower the baseline for your citizens' happiness.
     :tags: fort gameplay units
 
-When enabled, negative thoughts that your citizens have will multiply by the
-specified factor. This makes it more challenging to keep them happy.
+When enabled, all of your citizens receive a negative thought about a
+particularly nasty soapy bath. You can vary the strength of this negative
+thought to increase or decrease the difficulty of keeping your citizens happy.
 
 Usage
 -----
@@ -18,18 +19,18 @@ Usage
     misery <factor>
     misery clear
 
-The default misery factor is ``2``, meaning that your dwarves will become
-miserable twice as fast.
+The default misery factor is ``2``, which will result in a moderate hit to your
+dwarves' happiness. Larger numbers increase the challenge.
 
 Examples
 --------
 
 ``enable misery``
-    Start multiplying bad thoughts for your citizens!
+    Start adding bad thoughts about nasty soapy baths to your citizens!
 
 ``misery 5``
-    Make dwarves become unhappy 5 times faster than normal -- this is quite
-    challenging to handle!
+    Change the strength of the soapy bath negative thought to something quite
+    large -- this is very challenging to handle!
 
 ``misery clear``
     Clear away negative thoughts added by ``misery``. Note that this will not