diff --git a/doc/userguide/configuration/multi-tenant.rst b/doc/userguide/configuration/multi-tenant.rst
index d2b0496b8779..e727facf5d9e 100644
--- a/doc/userguide/configuration/multi-tenant.rst
+++ b/doc/userguide/configuration/multi-tenant.rst
@@ -4,31 +4,31 @@ Multi Tenancy
 Introduction
 ------------
 
-Multi tenancy support allows for different rule sets with different
-rule vars. These tenants can then be assigned to VLANs or interfaces
-(devices).
+Multi tenancy support allows different tenants to use different
+rule sets with different rule variables.
+
+Tenants are identified by their `selector`; a `selector` can be
+a VLAN, interface/device, or from a pcap file ("direct").
 
 YAML
 ----
 
-In the main ("master") YAML, the suricata.yaml, a new section called
-"multi-detect" should be added.
+Add a new section in the main ("master") Suricata configuration file -- ``suricata.yaml`` -- named ``multi-detect``.
 
 Settings:
 
-* enabled: yes/no -> is multi-tenancy support enabled
-* default: yes/no -> is the normal detect config a default 'fall back' tenant?
-* selector: direct (for unix socket pcap processing, see below), vlan or device
-* loaders: number of 'loader' threads, for parallel tenant loading at startup
-* tenants: list of tenants
+* `enabled`: yes/no -> is multi-tenancy support enabled
+* `selector`: direct (for unix socket pcap processing, see below), VLAN or device
+* `loaders`: number of `loader` threads, for parallel tenant loading at startup
+* `tenants`: list of tenants
 
   * id: tenant id (numeric values only)
   * yaml: separate yaml file with the tenant specific settings
 
-* mappings:
+* `mappings`:
 
-  * vlan id or device
-  * tenant id: tenant to associate with the vlan id / device
+  * VLAN id or device: The outermost VLAN is used to match.
+  * tenant id: tenant to associate with the VLAN id or device
 
 ::
 
@@ -93,12 +93,13 @@ configuration:
 
       ...
 
-vlanid
-~~~~~~
+vlan-id
+~~~~~~~
 
-Assign tenants to vlan id's.
+Assign tenants to VLAN ids. Suricata matches the outermost VLAN id with this value.
+Multiple VLANs can have the same tenant id. VLAN id values must be between 1 and 4094.
 
-Example of vlan mapping::
+Example of VLAN mapping::
 
     mappings:
     - vlan-id: 1000
@@ -110,13 +111,13 @@ Example of vlan mapping::
 
 The mappings can also be modified over the unix socket, see below.
 
-Note: can only be used if 'vlan.use-for-tracking' is enabled.
+Note: can only be used if ``vlan.use-for-tracking`` is enabled.
 
 device
 ~~~~~~
 
 Assign tenants to devices. A single tenant can be assigned to a device.
-Multiple devices can have the same tenant.
+Multiple devices can have the same tenant id.
 
 Example of device mapping::
 
@@ -152,7 +153,7 @@ Unix Socket
 Registration
 ~~~~~~~~~~~~
 
-register-tenant <id> <yaml>
+``register-tenant <id> <yaml>``
 
 Examples:
 
@@ -164,7 +165,7 @@ Examples:
   register-tenant 5 tenant-5.yaml
   register-tenant 7 tenant-7.yaml
 
-unregister-tenant <id>
+``unregister-tenant <id>``
 
 ::
 
@@ -174,8 +175,8 @@ unregister-tenant <id>
 Unix socket runmode (pcap processing)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The Unix Socket "pcap-file" command can be used to select the tenant
-to inspect the pcap against:
+The Unix Socket ``pcap-file``  command is used to associate the tenant with
+the pcap:
 
 ::
 
@@ -191,22 +192,22 @@ traffic2.pcap against tenant 2 and logs to /logs2/ and so on.
 Live traffic mode
 ~~~~~~~~~~~~~~~~~
 
-For live traffic currently only a vlan based multi-tenancy is supported.
+Multi-tenancy supports both VLAN and devices with live traffic.
 
-The master yaml needs to have the selector set to "vlan".
+In the master configuration yaml file, specify ``device`` or ``vlan`` for the ``selector`` setting.
 
 Registration
 ~~~~~~~~~~~~
 
-Tenants can be mapped to vlan id's.
+Tenants can be mapped to vlan ids.
 
-register-tenant-handler <tenant id> vlan <vlan id>
+``register-tenant-handler <tenant id> vlan <vlan id>``
 
 ::
 
   register-tenant-handler 1 vlan 1000
 
-unregister-tenant-handler <tenant id> vlan <vlan id>
+``unregister-tenant-handler <tenant id> vlan <vlan id>``
 
 ::