diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md
index 74a567c00bf0d16f28455fd64a1e24e3b4f8ee4c..e9ecfff4424fe1f3b1e4755936c0f42ba57bf92b 100644
--- a/docs/sources/reference/run.md
+++ b/docs/sources/reference/run.md
@@ -302,6 +302,19 @@ get the same proportion of CPU cycles, but you can tell the kernel to
 give more shares of CPU time to one or more containers when you start
 them via Docker.
 
+The flag `-c` or `--cpu-shares` with value 0 indicates that the running
+container has access to all 1024 (default) CPU shares. However, this value
+can be modified to run a container with a different priority or different
+proportion of CPU cycles.
+
+E.g., If we start three {C0, C1, C2} containers with default values
+(`-c` OR `--cpu-shares` = 0) and one {C3} with (`-c` or `--cpu-shares`=512)
+then C0, C1, and C2 would have access to 100% CPU shares (1024) and C3 would
+only have access to 50% CPU shares (512). In the context of a time-sliced OS
+with time quantum set as 100 milliseconds, containers C0, C1, and C2 will run
+for full-time quantum, and container C3 will run for half-time quantum i.e 50
+milliseconds.
+
 ## Runtime privilege, Linux capabilities, and LXC configuration
 
     --cap-add: Add Linux capabilities