From 61e0a5adf7e32140758e5ea2b7a230228255fc71 Mon Sep 17 00:00:00 2001
From: Gagan Deep <pandafy.dev@gmail.com>
Date: Fri, 30 Jun 2023 22:17:37 +0530
Subject: [PATCH] [req-changes] Updated docs

---
 README.rst | 41 +++++++++++++++++++++++++++++++++++------
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/README.rst b/README.rst
index 4994eb819..b3837e225 100644
--- a/README.rst
+++ b/README.rst
@@ -531,7 +531,14 @@ with templates, this feature is also known as *configuration context*, think of
 it like a dictionary which is passed to the function which renders the
 configuration, so that it can fill variables according to the passed context.
 
-The different ways in which variables are defined are described below.
+The different ways in which variables are defined are described below in
+the order (high to low) of their precedence:
+
+1. `User defined device variables <#user-defined-device-variables>`_
+2. `Predefined device variables <#predefined-device-variables>`_
+3. `Global variables <#global-variables>`_
+4. `Group variables <#group-variables>`_
+5. `Template default values <#template-default-values>`_
 
 Predefined device variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -574,6 +581,14 @@ The default values of variables can be manipulated from the section
 .. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/template-default-values.png
   :alt: default values
 
+Group variables
+~~~~~~~~~~~~~~~
+
+Variables can also be defined in `Device groups <#device-groups>`_.
+
+Refer the `Group configuration variables <group-configuration-variables>`_
+section for detailed information.
+
 Global variables
 ~~~~~~~~~~~~~~~~
 
@@ -931,11 +946,7 @@ Device Groups provide features aimed at adding specific management rules
 for the devices of an organization:
 
 - Group similar devices by having dedicated groups for access points, routers, etc.
-- Store additional information regarding a group in the structured metadata field
-  (which can be accessed via the REST API).
-- Customize structure and validation of metadata field of DeviceGroup to standardize
-  information across all groups using `"OPENWISP_CONTROLLER_DEVICE_GROUP_SCHEMA" <#openwisp-controller-device-group-schema>`_
-  setting.
+- Define `group metadata <#group-metadata>`_.
 - Define `group configuration templates <#group-templates>`_.
 - Define `group configuration variables <#group-configuration-variables>`_.
 
@@ -985,10 +996,28 @@ Group Configuration Variables
 
 Groups allow to define configuration variables which are automatically
 added to the device's context in the **System Defined Variables**.
+Check the `"How to use configuration variables" section <#how-to-use-configuration-variables>`_
+to learn about precedence of different configuration variables.
 
 This feature works also when editing group templates or the group assigned
 to a device via the `REST API <#change-device-group-detail>`__.
 
+Group Metadata
+##############
+
+Groups allow to store additional information regarding a group in the
+structured metadata field (which can be accessed via the REST API).
+
+The metadata field allows custom structure and validation to standardize
+information across all groups using the
+`"OPENWISP_CONTROLLER_DEVICE_GROUP_SCHEMA" <#openwisp-controller-device-group-schema>`_
+setting.
+
+**Note:** *Group configuration variables* and *Group metadata* serves different purposes.
+The group configuration variables should be used when the devie configuration is required
+to be changed for particular group of devices. Group metadata should be used to store
+additional data for the devices. Group metadata is not used for configuration generation.
+
 Export/Import Device data
 ~~~~~~~~~~~~~~~~~~~~~~~~~