diff --git a/README.md b/README.md
index a87673a9..153e2742 100644
--- a/README.md
+++ b/README.md
@@ -199,6 +199,27 @@ init file:
 (require 'smartparens-config)
 ```
 
+### eldoc
+
+By default racket-mode sets `eldoc-documentation-function` to `nil` --
+no `eldoc-mode` support. You may set it to `racket-eldoc-function` in
+a `racket-mode-hook` if you really want to use `eldoc-mode` with
+Racket. But it is not a very satisfying experience because Racket is
+not a very "eldoc-friendly" language. Although racket-mode attempts
+to discover argument lists, contracts, or types this doesn't work in
+many common cases:
+
+- Many Racket functions are defined in `#%kernel`. There's no easy way
+  to determine their argument lists. Most are not `provide`d with a
+  contract.
+
+- Many of the interesting Racket forms are syntax (macros) not
+  functions. There's no easy way to determine their "argument
+  lists".
+
+A more satisfying experience is to use `racket-describe' or
+`racket-doc'.
+
 ## Documentation
 
 Within Emacs, use the usual help functions.
diff --git a/racket-common.el b/racket-common.el
index c113cb44..8fe2ecc8 100644
--- a/racket-common.el
+++ b/racket-common.el
@@ -242,7 +242,7 @@ a list of all modes in which Racket is edited."
   (racket--set-indentation)
   (setq-local indent-tabs-mode nil)
   (setq-local completion-at-point-functions (list #'racket-complete-at-point))
-  (setq-local eldoc-documentation-function #'racket-eldoc-function)
+  (setq-local eldoc-documentation-function nil)
   (setq-local beginning-of-defun-function #'racket--beginning-of-defun-function))
 
 
diff --git a/racket-complete.el b/racket-complete.el
index 0376436d..5dcce9d2 100644
--- a/racket-complete.el
+++ b/racket-complete.el
@@ -143,6 +143,26 @@ prompt uses READER, which must be a function like
 ;;; eldoc
 
 (defun racket-eldoc-function ()
+  "A value suitable for the variable `eldoc-documentation-function'.
+
+By default racket-mode sets `eldoc-documentation-function' to nil
+-- no `eldoc-mode' support. You may set it to this function in a
+`racket-mode-hook' if you really want to use `eldoc-mode' with
+Racket. But it is not a very satisfying experience because Racket
+is not a very \"eldoc friendly\" language. Although racket-mode
+attempts to discover argument lists, contracts, or types this
+doesn't work in many common cases:
+
+- Many Racket functions are defined in #%kernel. There's no easy
+  way to determine their argument lists. Most are not provided
+  with a contract.
+
+- Many of the interesting Racket forms are syntax (macros) not
+  functions. There's no easy way to determine their \"argument
+  lists\".
+
+A more satisfying experience is to use `racket-describe' or
+`racket-doc'."
   (and (racket--repl-live-p)
        (> (point) (point-min))
        (save-excursion