Describe new layer tree insertion methods - fixes #8038

docs/user_manual/introduction/general_tools.rst

@@ -49,6 +49,31 @@ The :guilabel:`Layers` panel (also called the ``map legend``) lists all
 the layers in the project and helps you manage their visibility and shape the map.
 You can show or hide the panel by pressing :kbd:`Ctrl+1`.
 
+QGIS provides a variety of ways to add layers to a project:
+
+* using the :guilabel:`Add` button from the dedicated data provider tab
+  in the :ref:`Data source manager <opening_data>` dialog
+* from QGIS :ref:`Browser panel <label_browserpanel>` or :ref:`DB Manager <dbmanager>`:
+  double-click, drag-and-drop files and layers onto QGIS or use the contextual menu
+* drag-and-drop files from the Operating System files explorer onto QGIS
+
+In all these scenarios, you can open one or many layers at a time.
+New layers are added to the :guilabel:`Layers` panel:
+
+#. if dropped over the :guilabel:`Layers` panel, at the exact location they are released
+#. in the other cases, at a location that respects the global :ref:`behavior used when adding new layers
+   <layer_tree_insertion_methods>` setting
+#. and in case of multiple layers, they are sorted in a way
+   that increases the chance of their stacking being logical
+   and features being visible as most as possible, using the following logic (top to bottom):
+
+   * vector point layers
+   * vector line layers
+   * vector polygon layers
+   * point cloud layers
+   * mesh layers
+   * raster layers
+
 At the top of the :guilabel:`Layers` panel, a toolbar allows you to:
 
 * |symbology| :sup:`Open the layer styling dock (F7)`: toggle the

docs/user_manual/introduction/qgis_configuration.rst

@@ -692,11 +692,27 @@ These properties let you set:
 
 * **Layer legend** interaction:
 
-  * :guilabel:`Double click action in legend` |selectString|. You can either
-    'Open layer properties', 'Open attribute table' or 'Open layer styling dock'
-    with the double click.
-  * |unchecked| :guilabel:`Show feature count for newly added layers`: displays
-    in the :guilabel:`Layers` panel the number of features next to the layer name.
+  * :guilabel:`Double click action in legend`: whether a double-click on a layer should either
+    :guilabel:`Open layer properties` (default), :guilabel:`Open attribute table`
+    or :guilabel:`Open layer styling dock`.
+
+  .. _layer_tree_insertion_methods:
+
+  * :guilabel:`Behavior used when adding new layers`: determines where layers are placed
+    in the :guilabel:`Layers` panel when loaded into QGIS. It can be:
+
+    * :guilabel:`Above currently selected layer`
+    * :guilabel:`Always on top of the layer tree`
+    * :guilabel:`Optimal index within current layer tree group`:
+      Unlike the other options that sort the new layers among them
+      and place them as a stack at the desired location,
+      this option extents the sorting logic to the whole layer tree (or the active group)
+      and inserts new layers in an "optimal" fashion
+      by insuring that point layers sit on top of point layers,
+      followed by line layers on top of lines, followed by polygon layers, etc.
+
+  * |unchecked| :guilabel:`Show feature count for newly added layers`:
+    displays in the :guilabel:`Layers` panel the number of features next to the layer name.
     Feature count of classes, if any, is as well displayed.
     You can right-click on a layer to turn on/off its feature count.
   * |unchecked| :guilabel:`Display classification attribute names` in the Layers