updated translations and documentation style

.gitignore

@@ -2,4 +2,5 @@
 *~
 /_build
 .transifexrc
-.tx
+.tx
+.DS_Store

README.md

@@ -1,100 +1,98 @@
-# Zammad user documentation
+[![Documentation Status][badge]][docs]
 
-If you want to contribute to the Zammad documentation you can edit the rst files and create pull requests.
+# Zammad User Documentation
 
-We take care about the translation part, so please don't change anything else whithin the repository. These changes would be discarded anyway ;)
+Source files for [Zammad’s user documentation][docs].
 
-## Note:
-**Please modify only *.rst files** the *.PO and *.MO files are autogenerated!
+## Contributing
 
-## ReStructuredText markup
+If you would like to improve the docs, simply:
 
-If you like to edit the docs use the ReStructuredText markup language. Info about this markup language can be found at:
+1. fork the repo,
+2. edit the appropriate `.rst` files (see [Markup Format](#markup-format) below), and
+3. submit a pull request.
 
-- http://www.sphinx-doc.org/en/stable/rest.html
-- http://docs.readthedocs.io/en/latest/_themes/sphinx_rtd_theme/demo_docs/source/demo.html
+> **🌍 Note on localization:** Translations are prepared and stored on
+> [Transifex][tfx], a third-party cloud platform. Do **NOT** manually edit the
+> `.po` and `.mo` localization files, as any such changes will be overwritten
+> in the compilation process.
 
-Thanks! ❤ ❤ ❤
+Thanks! ❤ ❤ ❤  
+The Zammad Team
 
-  Zammad Team
+### Markup Format
 
-[![Documentation Status](https://readthedocs.org/projects/zammad-user-documentation/badge/?version=latest)](https://zammad-user-documentation.readthedocs.io/de/latest/)
+These docs are written using the ReStructuredText markup format. Info about
+this markup language can be found at:
 
-## Local tests (mostly internal stuff)
+- <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>
+- <https://sphinx-rtd-theme.readthedocs.io/en/latest/demo/structure.html>
 
-If you want to test the docs for yourself you need a local installation of sphinx and gettext.
+## Compilation
 
-```
-pip install sphinx sphinx-autobuild sphinx-intl sphinx_rtd_theme
+### Dependencies
 
-```
+* sphinx
 
-### Example for a local HTML build
+  ```
+  $ pip install sphinx sphinx-autobuild sphinx-intl sphinx_rtd_theme
+  ```
 
-```
-make html
-```
+* gettext
 
-### Example workflow for localization using transifex
+  ```
+  $ brew install gettext              # macOS
+  $ sudo apt install gettext          # Debian / Ubuntu
+  $ sudo dnf install gettext          # Fedora
+  ...
+  ```
 
-If you have to work on the translations you need gettext.
+* transifex-client (optional)
 
-For OS X use HomeBrew or build from source. For Linux use your package manager.
+  ```
+  $ pip install transifex-client
+  ```
 
-```
-brew install gettext
-```
+### Local HTML build
 
-The workflow itself
-
-### create .tx config
 ```
-tx init
+$ make html
 ```
 
-### or if you just want to update a ressource
-```
-tx set --source -r <project_slug.resource_slug> -l <lang> <file>
+### Localization using transifex
 
-make clean
-```
-
-### this will generate the strings from the *.rst files
-```
-make gettext
 ```
+# create .tx config
+$ tx init
 
-### this will generate the locales (DE|EN)
-```
-sphinx-intl update -p _build/locale/ -l de -l en
-```
+# or if you just want to update a resource
+$ tx set --source -r <project_slug.resource_slug> -l <lang> <file>
+$ make clean
 
-### this will update the resource files from the pot dir
-```
-sphinx-intl update-txconfig-resources --pot-dir _build/locale --transifex-project-name zammad-user-documentation
-```
+# generate the strings from the *.rst files
+$ make gettext
 
-### push to transifex (if configured)
-```
-tx push -s
-```
+# generate the locales (DE|EN)
+$ sphinx-intl update -p _build/locale/ -l de -l en
 
-### after translation pull needed languages from transifex
-```
-tx pull -l en
-```
+# update the resource files from the pot dir
+$ sphinx-intl update-txconfig-resources --pot-dir _build/locale --transifex-project-name zammad-user-documentation
 
-### build the .MO files for use with readthedocs
-```
-sh build_mo.sh
-```
+# push to transifex (if configured)
+$ tx push -s
 
-After a successful build, push to this repo and readthedocs will update itself.
+# after translation pull needed languages from transifex
+$ tx pull -l en
 
-### manual language-based build (_build/html/) (for testing)
+# build the .MO files for use with readthedocs
+# (After a successful build, push to this repo and readthedocs will update itself.)
+$ sh build_mo.sh
 
+# manual language-based build (`_build/html/`) (for testing)
+$ make -e SPHINXOPTS="-D language='de'" html
+$ make -e SPHINXOPTS="-D language='en'" html
 ```
-make -e SPHINXOPTS="-D language='de'" html
-make -e SPHINXOPTS="-D language='en'" html
 
-```
+[badge]: https://readthedocs.org/projects/zammad-user-documentation/badge/?version=latest
+[docs]: https://zammad-user-documentation.readthedocs.io/en/latest/
+[tfx]: https://www.transifex.com/

advanced/keyboard-shortcuts.rst

@@ -0,0 +1,47 @@
+:orphan:
+
+Keyboard Shortcuts
+==================
+
+Zammad supports a wide array of keyboard shortcuts to expedite your workflow as an expert user.
+
+.. figure:: /images/advanced/keyboard-shortcuts.jpg
+   :alt: Keyboard shortcut cheat sheet
+   :align: center
+   :scale: 50%
+
+   The keyboard shortcut cheat sheet on macOS.
+
+.. tip:: **🖱️ UI Protip**
+
+   Click on your avatar at the bottom of the main menu to access the **keyboard
+   shortcuts cheat sheet**.
+
+   .. figure:: /images/extras/profile-and-settings.jpg
+      :alt: User submenu
+      :align: center
+      :scale: 50%
+
+   Alternately, bring it up with one of the shortcuts below
+   (shortcut-ception!)
+
+      * ``Ctrl`` + ``Shift`` + ``H`` (on Windows)
+      * ``Ctrl`` + ``Shift`` + ``H`` (on Linux)
+      * ``Cmd`` + ``Ctrl`` + ``Shift`` + ``H`` (on macOS)
+
+Formatting Text
+---------------
+
+Keyboard shortcuts can be used to apply rich-text formatting in one of two ways:
+
+:As-you-type:
+
+   * Press ``Cmd`` + ``I`` to enter Italics mode,
+   * enter your desired text, and
+   * press ``Cmd`` + ``I`` again to return to normal text mode.
+
+:All-at-once:
+
+   * Enter your desired text,
+   * click-and-drag with the mouse to select it, and
+   * press ``Cmd`` + ``I`` to italicize.

advanced/search.rst

@@ -0,0 +1,89 @@
+Advanced Search
+===============
+
+With Zammad, you can limit your search to specific Information. With this you're able to search tickets with specific key words and states, enabling you to improve your search results.
+
+For instance, you can search for a specific customer by using::
+
+  customer: some name
+  
+If you want to search more complex, you can use conditions with () and AND/OR options::
+
+  state: open and (from:me OR from:somebody)
+  
+Available attributes
+--------------------
+
+
+.. hint:: For a more detailed list of available attributes please take a look into our `Zammad Admin-Documentation <https://docs.zammad.org/en/latest/install-elasticsearch.html#list-of-values-which-are-stored-in-elasticsearch>`_ 
+
+
+.. |br| raw:: html
+
+   <br />
+
+.. csv-table:: Attributes and their usuage
+   :header: "Attribute", "possible Values", "Example", "Description"
+   :widths: 10, 10, 10, 20
+
+   "number", "1118566", "number:1118566 |br|\ number:11185*", "Search for a Ticketnumber"
+   "title", "some title", "title:""some title"" |br|\ title:Printer |br|\ title: ""some ti*""", "If you need to use spacings in the search phrase, use quotes. Zammad will do a AND-Search over the given words. You can also use a single keyword without quotation."
+   "created_at", "2018-11-18", "created_at:2018-11-18 |br|\ created_at:[2018-11-15 TO 2018-11-18] |br|\ created_at:>now-1h", "You can either use a simple date, a date-range or >now-xh. Please note that the date format needs to be YYYY-MM-DD"
+   "state", "new |br|\ open |br|\ closed", "state: new |br|\ state:new OR open", "You can filter for specific ticket states (and even combine them with an OR). Please note that you need to use the english namings for states, unless you have custom ticket states defined in your instance."
+   "article_count", "5 |br|\ [5 TO 10] |br|\ [5 TO \*] |br|\ [\* TO 5]", "article_count:5 |br|\ article_count: [5 TO 10] |br|\ article_count:[5 TO \*] |br|\ article_count:[\* TO 5]", "You can search for Tickets with a specific number of articles (you can even search for everything with 5 or more articles or even up to 5 articles, if needed)."
+   "article.from", "\*bob\*", "article.from:\*bob\*", "Show all tickets that contain articles from ""Bob"""
+   "article.body", "heat |br|\ heat~ |br|\ /joh?n(ath[oa]n)/", "article.body:heat |br|\ article.body:heat~ |br|\ articlebody:/joh?n(ath[oa]n)/", "First example shows every ticket containing the word ""heat"" - you can also use the fuzzy operator ""~"" to search for similar words like e.g. like ""head"". Zammad will also allow you to use regular expressions, where ever the attributes allows it."
+
+.. hint:: Combining search phrases
+  You can combine search phrases by using ``AND``, ``OR`` and ``TO``, depending on the situation and phrases you use.
+  If needed, you can parts of your search phrase for complex searches with ``()``. This allows you to combine several phrases with different dependencies (AND/OR). In case you receive search results that you want to exclude, you can use negation ``!``. Below are some examples that you could use with this:
+
+  .. csv-table:: Examples for search phrase combinations
+   :header: "Search phrase", "Description"
+   :widths: 10, 20
+
+   "state:(closed OR open) AND (priority:""2 normal"" OR tag:feedback)", "Show every ticket that state is either closed or open and has priority normal or the tag feedback."
+   "state:(closed OR open) AND (priority:""2 normal"" OR tag:feedback) AND !(*Zammad*)", "This gets the same result as above, expect that we don't want the ticket to contain anything matching to ""Zammad"""
+   "owner.email:bob@example.net AND state:(open OR new)", "Show Tickets from bob@example.net that are either open or new"
+   "state:pending* AND article_count:[1 TO 5]", "Show everything with any pending state and an article count of 1 to 5."
+
+
+Some Ticket attributes and their type
+-------------------------------------
+
+Below you can find the most important attributes sorted by ticket and article.
+
+Ticket attributes
+^^^^^^^^^^^^^^^^^
+
+* number: string
+* title: string
+* group: string
+* priority: string
+* state: string
+* organization: string
+* owner: object (owner.firstname, owner.lastname, owner.email, ...)
+* customer: object (customer.firstname, customer.lastname, customer.email, ...)
+* first_response_at: timestamp
+* first_response_in_min: integer (business min till first response)
+* close_at: timestamp
+* close_in_min: integer (business min till close)
+* last_contact_at: timestamp (last contact by customer or agent)
+* last_contact_agent_at: timestamp (last contact by agent)
+* last_contact_customer_at: timestamp (last contact by customer)
+* create_article_type: string (email|phone|web|...)
+* create_article_sender: string (Customer|Agent|System)
+* article_count: integer
+* escalation_at: timestamp
+* pending_time: timestamp
+
+Article attributes
+^^^^^^^^^^^^^^^^^^
+
+* article.from: string
+* article.to: string
+* article.cc: string
+* article.subject: string
+* article.body: string
+* article.attachment._name: string (filename of attachment)
+* article.attachment._content: string (content of attachment)

advanced/suggested-workflows.rst

@@ -0,0 +1,41 @@
+Suggested Workflows
+===================
+
+.. _sharing-work:
+
+Sharing Work on a Ticket
+------------------------
+
+When a ticket is complex enough,
+it may require attention from more than one agent
+(or even more than one department!).
+
+In these cases, the simplest thing to do
+is usually just to **take turns working on the ticket**.
+(:doc:`Splitting tickets </advanced/ticket-actions/split>` is another option,
+best reserved for when a ticket really encompasses multiple problems,
+or when taking turns would needlessly block one agent’s progress.)
+
+.. figure:: /images/advanced/suggested-workflows-sharing-work.jpg
+   :alt: Reassigning tickets in the ticket pane
+   :align: center
+
+   Reassign a ticket (via the *Group* and *Owner* settings)
+   to let colleagues know you’re done with your part.
+
+How it works
+^^^^^^^^^^^^
+
+Suppose a call comes into the sales department.
+A sales rep takes the call, creates a ticket,
+and looks up some prices for the customer.
+After recording his notes,
+the rep then decides that this ticket needs to be passed onto customer service.
+
+Our sales rep can simply un-assign himself has the **owner** of the ticket
+and re-assign the ticket to the Customer Service **group**.
+*All customer service agents will be notified of the incoming ticket*,
+and the first available agent can assign herself
+to pick up where the sales rep left off.
+
+.. tip:: Be sure to leave notes with as much information as possible for the next agent!