Fix #20: Explain the difference between path and ordering

Author: matthiask

README.rst

@@ -26,10 +26,12 @@ Features and limitations
 - The fields added by the common table expression always are
   ``tree_depth``, ``tree_path`` and ``tree_ordering``. The names cannot
   be changed. ``tree_depth`` is an integer, ``tree_path`` an array of
-  primary keys and ``tree_ordering`` an array of values used for
-  ordering nodes within their siblings. Note that the contents of the
-  ``tree_path`` and ``tree_ordering`` are subject to change. You shouldn't rely
-  on their contents.
+  primary keys representing the path from the root to the current node
+  (including the current node itself), and ``tree_ordering`` an array of
+  values used for ordering nodes within their siblings at each level of
+  the tree hierarchy. Note that the contents of the ``tree_path`` and
+  ``tree_ordering`` are subject to change. You shouldn't rely on their
+  contents.
 - Besides adding the fields mentioned above the package only adds queryset
   methods for ordering siblings and filtering ancestors and descendants. Other
   features may be useful, but will not be added to the package just because
@@ -182,6 +184,53 @@ Basic usage
     nodes = Node.objects.with_tree_fields().without_tree_fields()
 
 
+Understanding tree fields
+-------------------------
+
+When using ``with_tree_fields()``, each node gets three additional attributes:
+
+- **``tree_depth``**: An integer representing the depth of the node in the tree
+  (root nodes have depth 0)
+- **``tree_path``**: An array containing the primary keys of all ancestors plus
+  the current node itself, representing the path from root to current node
+- **``tree_ordering``**: An array containing the ordering/ranking values used
+  for sibling ordering at each level of the tree hierarchy
+
+The key difference between ``tree_path`` and ``tree_ordering``:
+
+.. code-block:: python
+
+    # Example tree structure:
+    #   Root (pk=1, order=0)
+    #   ├── Child A (pk=2, order=10)
+    #   │   └── Grandchild (pk=4, order=5)
+    #   └── Child B (pk=3, order=20)
+
+    # For the Grandchild node:
+    grandchild = Node.objects.with_tree_fields().get(pk=4)
+
+    # tree_path shows the route through primary keys: Root -> Child A -> Grandchild
+    assert grandchild.tree_path == [1, 2, 4]  # [root.pk, child_a.pk, grandchild.pk]
+
+    # tree_ordering shows ordering values at each level: Root's order, Child A's order, Grandchild's order
+    assert grandchild.tree_ordering == [0, 10, 5]  # [root.order, child_a.order, grandchild.order]
+
+**Important note**: When not using an explicit ordering (like a ``position``
+field), siblings are ordered by their primary key by default. This means
+``tree_path`` and ``tree_ordering`` will contain the same values. While this
+may be fine for your use case consider adding an explicit ordering field:
+
+.. code-block:: python
+
+    class Node(TreeNode):
+        id = models.UUIDField(primary_key=True, default=uuid.uuid4)
+        name = models.CharField(max_length=100)
+        position = models.PositiveIntegerField(default=0)
+
+        class Meta:
+            ordering = ["position"]
+
+
 Filtering tree subsets
 ----------------------