1 files changed, 14 insertions, 4 deletions

diff --git a/src/frame.c b/src/frame.c
index b7ff7fd1fc4..b3990ae2aa5 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -6233,14 +6233,24 @@ You can also use a floating number between 0.0 and 1.0.  */);
                doc: /* Alist of default values for frame creation.
 These may be set in your init file, like this:
   (setq default-frame-alist \\='((width . 80) (height . 55) (menu-bar-lines . 1)))
+
 These override values given in window system configuration data,
- including X Windows' defaults database.
+including X Windows' defaults database.
+
+Note that many display-related modes (like `scroll-bar-mode' or
+`menu-bar-mode') alter `default-frame-alist', so if you set this
+variable directly, you may be overriding other settings
+unintentionally.  Instead it's often better to use
+`modify-all-frames-parameters' or push new elements to the front of
+this alist.
+
 For values specific to the first Emacs frame, see `initial-frame-alist'.
+
 For window-system specific values, see `window-system-default-frame-alist'.
+
 For values specific to the separate minibuffer frame, see
- `minibuffer-frame-alist'.
-The `menu-bar-lines' element of the list controls whether new frames
- have menu bars; `menu-bar-mode' works by altering this element.
+`minibuffer-frame-alist'.
+
 Setting this variable does not affect existing frames, only new ones.  */);
   Vdefault_frame_alist = Qnil;