Draft: Fixes #470 - Tweak user docs

.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "spellright.language": [
+        "English (American)"
+    ],
+    "spellright.documentTypes": [
+        "markdown",
+        "latex",
+        "plaintext"
+    ]
+}

advanced/macros.rst

@@ -26,10 +26,8 @@ from the **Update ^** submenu in the Ticket View:
 
 .. tip:: 💾 **Macro = Update**
 
-   If you've made changes to any other
-   :ref:`settings on the ticket <ticket_settings>`
-   (including typing up a reply to the customer),
-   applying a macro will save them, too.
+   If you've made any changes (including typing up a reply to the customer),
+   applying a macro will save/send them too.
 
    ⚠️ **But beware:** in the event of a conflict,
    the macro's actions override any manual changes -

basics/find-ticket.rst

@@ -1,13 +1,101 @@
-Finding Tickets
-===============
+Find Tickets
+============
 
-If you plan to work on tickets, you'd better know how to find them first.
+There are different ways to find tickets, depending on your use case.
 
-Read on to learn how to check for new tickets, and dig up old ones.
+.. _overviews:
 
-.. toctree::
-   :maxdepth: 1
-   :titlesonly:
+Via Overviews
+-------------
 
-   by Browsing <find-ticket/browse>
-   by Searching <find-ticket/search>
+If you search for new tickets to work on, your first look should be in the
+overview section.  This section gives you a rough overview. More details are
+covered in a separate overview page.
+
+You can either open it by clicking the **Overviews** button
+in the navigation bar or use the keyboard shortcut :kbd:`o`. You can think of
+overviews as some kind of ticket lists.
+By default, there are some built in overviews. For example, there is
+an overview called "Unassigned & Open Tickets" which might be a good starting
+point.
+
+- My Assigned Tickets: open tickets in which you are set as owner.
+- Unassigned & Open Tickets: open tickets which don't have an owner set.
+- My Pending Reached Tickets: tickets in which you are the owner, have
+  the *pending reminder* state and the pending reminder time is reached.
+- Open Tickets: open tickets.
+- Pending Reached Tickets: tickets which have the *pending reminder* state and
+  the pending reminder time is reached.
+- Escalated Tickets: tickets which are escalated or will escalate in the next
+  10 minutes.
+
+Your Zammad admin may have created additional overviews. These are based on
+conditions, which are basically rules, to define which ticket appears in which
+overview.
+
+.. figure:: /images/basics/find-ticket/browse.jpg
+   :alt: Sample view of Overviews
+   :align: center
+
+   Click **Overviews** in the main menu to browse tickets.
+
+You can adjust the overviews in some aspects:
+
+- Click on a column heading to change the sorting.
+- Click and drag column dividers to adjust the column's width.
+- Adjust the order of the overviews in your
+  :doc:`user profile </extras/profile-and-settings>`.
+
+The need for action is color coded and reflects mainly the
+:doc:`ticket states </basics/service-ticket/settings/state>`:
+
+.. include:: /snippets/ticket-state-type-circles.rst
+
+If you spot a circle with a blue/pink gradient, it indicates that an
+:doc:`AI agent </extras/ai-features>` is currently working on the ticket.
+
+:doc:`Ticket priorities </basics/service-ticket/settings/priority>` are
+color-coded as well and help you to distinguish between the different
+priorities:
+
+.. figure:: /images/basics/service-ticket/settings/priority-colors.png
+   :alt: Overview showing 3 tickets with different priorities
+   :align: center
+
+.. _search-tickets:
+
+Via Search
+----------
+
+Looking for an a specific ticket? Use the **search bar**:
+
+.. figure:: /images/basics/find-ticket/search.png
+   :align: center
+   :scale: 80%
+
+   Results appear immediately under the search bar as you type.
+
+It's not just for tickets! Results cover 💬 **chat logs**,
+👨 **customers**, and 🏢 **organizations**, too.
+
+**🔍 Here are just a few of the places the search engine will look:**
+
+* 📝 message subject/content
+* 👩 recipient names & email addresses
+* 📎 text in file attachments (really!)
+* 🏷️ user/organization metadata (e.g. notes stored on customer profiles)
+
+You can find a detailed search document in our
+`Advanced Search <../../advanced/search.html>`_ page.
+
+
+.. figure:: /images/basics/find-ticket/search-details.png
+   :align: center
+
+   For detailed results,
+   click the **Show Search Details →** link
+   just above the autocomplete list.
+
+.. tip:: **🖱️ UI Protip**
+
+   Click on column headings to change the display order.

basics/service-ticket/settings/tags.rst

@@ -10,7 +10,7 @@ to make it easier to find them in the future.
 
    Click on a tag name to view other tickets with the same tag.
 
-.. hint:: :doc:`Search for tickets with a given tag </basics/find-ticket/search>`
+.. hint:: :ref:`Search for tickets with a given tag <search-tickets>`
    with the ``tags:`` search filter.
    For instance, find all tickets with the **order** tag
    by searching for ``tags: order``.

basics/ticket-basics.rst

@@ -0,0 +1,77 @@
+Ticket Basics
+=============
+
+Introduction
+------------
+
+In Zammad, **tickets** are used to track customer service requests.
+The first time a customer contacts you (or the company) about something,
+Zammad creates a new ticket. Each message sent between you and the customer is
+added to that ticket until the issue is resolved, the customer is happy and the
+ticket is finally closed. Such a single message in a ticket is called
+**article**. So basically, you can see a **ticket** as a **conversation**
+between you and a customer about a single issue.
+
+.. figure:: /images/basics/what-is-a-ticket.png
+   :alt: Zammad UI with ticket detail view
+   :align: center
+
+   A ticket is a conversation between a customer and one or more agents.
+
+If you're completely new to a ticket system and handled your customer requests
+with an email client so far, you might think that a ticket system is
+complicated. But the opposite is the case:
+
+- All emails are now collected in Zammad (and requests from other channels might
+  be as well).
+- You and your colleagues can see who is working on which customer request
+  ("ticket").
+- The state of each request as well as the history (who did what?) is
+  transparent.
+- There is no duplicate work and nothing gets overlooked.
+- You can ask your colleagues directly in the ticket for help in difficult
+  cases.
+- With Zammad's intuitive UI, you can focus on what matters: to resolve customer
+  issues and answer customer questions.
+
+So, basically you can work with Zammad similar as with your email client. Except
+that a ticket has additional attributes. Read on to learn more.
+
+Ticket Attributes
+-----------------
+
+In addition to article, tickets have some additional meta information which are
+called attributes. The most important ones are:
+
+- **State**: reflects the current state of a ticket (mainly if a customer
+  request is resolved or not). By default, there are the following states:
+
+  - New: State for new tickets on which no one has worked on. When updating a
+    ticket the first time, it automatically switches to open.
+  - Open: State for tickets which aren't resolved yet and some work needs to be
+    done.
+  - Pending Close: State for tickets which are basically resolved but you don't
+    want to close immediately. This state requires you to enter a date and time
+    at which the ticket automatically switches to closed.
+  - Pending Reminder: State for open tickets which you want to get reminded to a
+    certain date and time. Requires you to enter a date and time at which you
+    want to get notified. For example useful if you had a question to a third
+    party and want to make sure that this issue won't be forgotten.
+- **Owner**: This is the person who is currently responsible for the ticket. In
+  case you need information from another colleague, you can either change
+  the owner to this person or mention the person in an article by typing
+  :kbd:`@` :kbd:`@` and selecting the user. In the latter case, the user gets
+  notified and is automatically subscribed to receive notifications on ticket
+  updates.
+- **Group**: This ticket attribute is useful for organizations with more than one
+  team. Depending on the permissions, you might not see the ticket after
+  changing the group and saving the changes.
+
+Depending on the configuration of your Zammad, you might even have more
+attributes available. It is possible to create custom fields for
+tickets (e.g. for groups and users too). You think such a custom field makes
+sense? Talk with your Zammad admin, it can be set up easily
+(:admin-docs:`admins can read more here </system/object/types.html>`).
+
+Now you might wonder where to find and change these attributes. In this case,
+head over to the :doc:`zammad-ui` page where it is described.

basics/zammad-glossary.rst

@@ -505,7 +505,7 @@ Overview
    ask your admin to create it.
 
    For more information please have a look in
-   :doc:`/basics/find-ticket/browse`.
+   :doc:`/basics/find-ticket`.
 
 Owner
    The owner of a ticket is the person responsible for it and ensures that it