diff --git a/basis/help/markup/markup.factor b/basis/help/markup/markup.factor
index 229a025442..75e6538243 100644
--- a/basis/help/markup/markup.factor
+++ b/basis/help/markup/markup.factor
@@ -1,9 +1,9 @@
 ! Copyright (C) 2005, 2009 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: accessors arrays assocs classes colors colors.constants
-combinators definitions definitions.icons effects fry generic
-hashtables help.stylesheet help.topics io io.styles kernel make
-math namespaces parser present prettyprint
+combinators combinators.smart definitions definitions.icons effects
+fry generic hashtables help.stylesheet help.topics io io.styles
+kernel make math namespaces parser present prettyprint
 prettyprint.stylesheet quotations see sequences sets slots
 sorting splitting strings vectors vocabs vocabs.loader words
 words.symbol ;
@@ -398,7 +398,12 @@ M: f ($instance)
 
 : $shuffle ( element -- )
     drop
-    "Shuffle word. Re-arranges the stack according to the stack effect pattern." $description ;
+    "Shuffle word. Rearranges the top of the datastack as indicated in the stack effect pattern." $description ;
+
+: $complex-shuffle ( element -- )
+    drop
+    "Shuffle word. Rearranges the top of the datastack as indicated in the stack effect pattern." $description
+    { "The data flow represented by this shuffle word can be more clearly expressed using " { $link "locals" } "." } $deprecated ;
 
 : $low-level-note ( children -- )
     drop
@@ -449,4 +454,4 @@ M: array elements*
     icons get >alist sort-keys
     [ [ <$link> ] [ definition-icon-path <$image> ] bi* swap ] assoc-map
     { "" "Definition class" } prefix
-    $table ;
\ No newline at end of file
+    $table ;
diff --git a/core/kernel/kernel-docs.factor b/core/kernel/kernel-docs.factor
index db842182b8..b837c0a3ff 100644
--- a/core/kernel/kernel-docs.factor
+++ b/core/kernel/kernel-docs.factor
@@ -14,20 +14,21 @@ HELP: 3drop ( x y z -- )             $shuffle ;
 HELP: dup   ( x -- x x )             $shuffle ;
 HELP: 2dup  ( x y -- x y x y )       $shuffle ;
 HELP: 3dup  ( x y z -- x y z x y z ) $shuffle ;
-HELP: rot   ( x y z -- y z x )       $shuffle ;
-HELP: -rot  ( x y z -- z x y )       $shuffle ;
-HELP: dupd  ( x y -- x x y )         $shuffle ;
-HELP: swapd ( x y z -- y x z )       $shuffle ;
 HELP: nip   ( x y -- y )             $shuffle ;
 HELP: 2nip  ( x y z -- z )           $shuffle ;
-HELP: tuck  ( x y -- y x y )         $shuffle ;
 HELP: over  ( x y -- x y x )         $shuffle ;
 HELP: 2over                          $shuffle ;
 HELP: pick  ( x y z -- x y z x )     $shuffle ;
 HELP: swap  ( x y -- y x )           $shuffle ;
-HELP: spin                           $shuffle ;
-HELP: roll                           $shuffle ;
-HELP: -roll                          $shuffle ;
+
+HELP: spin                     $complex-shuffle ;
+HELP: rot   ( x y z -- y z x ) $complex-shuffle ;
+HELP: -rot  ( x y z -- z x y ) $complex-shuffle ;
+HELP: dupd  ( x y -- x x y )   $complex-shuffle ;
+HELP: swapd ( x y z -- y x z ) $complex-shuffle ;
+HELP: tuck  ( x y -- y x y )   $complex-shuffle ;
+HELP: roll  $complex-shuffle ;
+HELP: -roll $complex-shuffle ;
 
 HELP: datastack ( -- ds )
 { $values { "ds" array } }
@@ -822,7 +823,7 @@ HELP: assert=
 { $description "Throws an " { $link assert } " error if " { $snippet "a" } " does not equal " { $snippet "b" } "." } ;
 
 ARTICLE: "shuffle-words-complex" "Complex shuffle words"
-"These shuffle words tend to make code difficult to read and reason about. Code that uses them should almost always be rewritten in terms of the " { $link "dataflow-combinators" } "."
+"These shuffle words tend to make code difficult to read and to reason about. Code that uses them should almost always be rewritten using " { $link "locals" } " or " { $link "dataflow-combinators" } "."
 $nl
 "Duplicating stack elements deep in the stack:"
 { $subsections
@@ -834,13 +835,13 @@ $nl
     swapd
     rot
     -rot
-    spin
     roll
     -roll
+    spin
 } ;
 
 ARTICLE: "shuffle-words" "Shuffle words"
-"Shuffle words rearrange items at the top of the data stack. They provide simple data flow control between words. More complex data flow control is available through the " { $link "dataflow-combinators" } "."
+"Shuffle words rearrange items at the top of the data stack as indicated by their stack effects. They provide simple data flow control between words. More complex data flow control is available with the " { $link "dataflow-combinators" } " and with " { $link "locals" } "."
 $nl
 "Removing stack elements:"
 { $subsections