diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 3d3f2562617..6f57bae8fef 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1024,10 +1024,11 @@ Outline Minor Mode
 mouse on the button toggles display of the section.  If the value of
 this variable is @code{insert}, the buttons are inserted directly into
 the buffer text, so @key{RET} on the button will also toggle display
-of the section, like a mouse click does.  If the value is
-@code{in-margins}, Outline minor mode will use the window margins to
-indicate that a section is hidden.  The buttons are customizable as icons
-(@pxref{Icons}).
+of the section, like a mouse click does.  Using the value @code{insert}
+is not recommended in editable buffers because it modifies them.
+If the value is @code{in-margins}, Outline minor mode will use the
+window margins to indicate that a section is hidden.  The buttons are
+customizable as icons (@pxref{Icons}).
 
 @vindex outline-minor-mode-cycle
   If the @code{outline-minor-mode-cycle} user option is
diff --git a/lisp/outline.el b/lisp/outline.el
index 97a51c9b92a..7cdfec753d1 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -314,12 +314,15 @@ outline-minor-mode-use-buttons
 When the value is `insert', additional placeholders for buttons are
 inserted to the buffer, so buttons are not only clickable,
 but also typing `RET' on them can hide and show the body.
+Using the value `insert' is not recommended in editable
+buffers because it modifies them.
 When the value is `in-margins', then clickable buttons are
 displayed in the margins before the headings.
 When the value is `t', clickable buttons are displayed
 in the buffer before the headings.  The values `t' and
 `in-margins' can be used in editing buffers because they
 don't modify the buffer."
+  ;; The value `insert' is not intended to be customizable.
   :type '(choice (const :tag "Do not use outline buttons" nil)
                  (const :tag "Show outline buttons in margins" in-margins)
                  (const :tag "Show outline buttons in buffer" t))