From a6fd23a5e48167e8d2f3eb6733694353b58c4241 Mon Sep 17 00:00:00 2001
From: Mateusz Pusz <mateusz.pusz@gmail.com>
Date: Mon, 26 Feb 2024 13:47:57 +0100
Subject: [PATCH] docs: unit symbols admonition extended in the "Quick Start"
 chapter

---
 docs/getting_started/quick_start.md | 47 ++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/docs/getting_started/quick_start.md b/docs/getting_started/quick_start.md
index 2ea00bbe..cad42756 100644
--- a/docs/getting_started/quick_start.md
+++ b/docs/getting_started/quick_start.md
@@ -91,11 +91,50 @@ The same can be obtained using optional unit symbols:
     quantity q = 42 * m / s;
     ```
 
-!!! tip
+!!! important
 
-    Unit symbols introduce a lot of short identifiers into the current scope, and that is
-    why they are opt-in. A user has to explicitly "import" them from a dedicated `unit_symbols`
-    namespace.
+    Unit symbols introduce a lot of short identifiers into the current scope, which may cause
+    naming collisions with unrelated but already existing identifiers in the code base.
+    This is why unit symbols are opt-in.
+    
+    A user has several options here to choose from depending on the required scenario and possible
+    naming conflicts:
+    
+    - explicitly "import" all of them from a dedicated `unit_symbols` namespace with a
+      [using-directive](https://en.cppreference.com/w/cpp/language/namespace#Using-directives):
+      
+        ```cpp
+        import mp_units;
+
+        using namespace mp_units;
+        using namespace mp_units::si::unit_symbols;  // imports all the SI symbols at once
+
+        quantity q = 42 * m / s;
+        ```
+
+    - selectively select only the required and not-conflicting ones with
+      [using-declarations](https://en.cppreference.com/w/cpp/language/using_declaration):
+
+        ```cpp
+        import mp_units;
+
+        using namespace mp_units;
+        using si::unit_symbols::m;
+        using si::unit_symbols::s;
+
+        quantity q = 42 * m / s;
+        ```
+
+    - specify a custom not conflicting unit identifier for a unit:
+
+        ```cpp
+        import mp_units;
+
+        using namespace mp_units;
+        constexpr Unit auto mps = si::metre / si::second;
+
+        quantity q = 42 * mps;
+        ```
 
 Quantities of the same kind can be added, subtracted, and compared to each other: