From 4ec50faf45429efc4e1f31b835b458d91b76195e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20=C5=A0pl=C3=ADchal?= <psplicha@redhat.com>
Date: Mon, 20 Apr 2020 21:33:59 +0200
Subject: [PATCH] Describe difference between --verbose and --debug

---
 docs/examples.rst      |  7 ++++---
 stories/cli/common.fmf | 22 +++++++++++++++++++++-
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/docs/examples.rst b/docs/examples.rst
index 4c034023eb..cbbb81b4da 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -6,9 +6,10 @@
 Let's have a look at a couple of real-life examples!
 
 You can obtain detailed list of available options for each command
-by invoking it with ``--help``. To control the verbosity of the
-output, use ``--debug`` and ``--quiet``. Depending on the command,
-``--verbose`` might be also available.
+by invoking it with ``--help``. In order to control the verbosity
+of the output use ``--verbose`` and ``--quiet``. To display
+implementation details for debugging use the ``--debug`` option.
+See :ref:`/stories/cli/common` options for details.
 
 Simply run ``tmt`` to get started with exploring your working
 directory::
diff --git a/stories/cli/common.fmf b/stories/cli/common.fmf
index 4ce279952b..d337d3d51d 100644
--- a/stories/cli/common.fmf
+++ b/stories/cli/common.fmf
@@ -4,8 +4,18 @@ story:
 
 /verbose:
     summary: Enable verbose output of the command
+    story:
+        As a user I want to see more detailed information for
+        particular command.
+    description: |
+        Different verbose levels can be enabled by using the
+        option several times. For example, discover step shows
+        only number of tests by default, list of tests in verbose
+        level one and could show some further test details in
+        higher verbose levels.
     example:
         - tmt test show -v
+        - tmt test show -vvv
         - tmt test show --verbose
     implemented: /tmt/cli
     documented: /tmt/cli
@@ -38,9 +48,19 @@ story:
     documented: /tmt/cli
 
 /debug:
-    summary: Print out everything tmt is doing
+    summary: Print additional information for debugging
+    story:
+        As a tmt developer I want to see as much details about
+        what's happening during execution so that I can easily
+        reveal bugs in the code.
+    description:
+        Debug level can be used to show detailed implementation
+        steps, revealing what's happening under the hood, so that
+        tool developers are able to more easily find bugs in the
+        code. Use the option multiple times to increase verbosity.
     example:
         - tmt run -d
+        - tmt run -ddd
         - tmt run --debug
     implemented: /tmt/cli
     documented: /tmt/cli