Skip to content

Commit

Permalink
Add S/MIME documentation for users (#34)
Browse files Browse the repository at this point in the history 
* WIP initial commit for smime documentary for agents

* add S/MIME introduction text and add link to index

* add S/MIME information on receiving signed and encrypted messages

This should help agents to verify received messages and, if something went wrong, how they can react.

* Add icon explanation for S/MIME

As Zammad introduces icons to the UI, we're explaining what each icon means in the UI here.

* add overwrite_css

This overwriting css files fixes too wide tables to fit into the content. This ensures that there are no vertical scroll bars which make it very hard to read the content itself.

* S/MIME add information on how to send signed/encrypted mails

* Smalld textual change because of changed default behavior

* Fix bad phrasing in links to admin docs

The user docs contain various references to admin docs,
some of which contained the following problems:

1. They assumed that the reader was also the administrator:

   > See the admin documentation for details.

   (Not all readers will have admin privileges, and thus
   it doesn't make sense to refer all readers to the admin docs.)

2. They misstated where certain features would be found:

   > .. note:: **🤔 Huh? I don’t see a “Time Accounting” dialog...**
   >
   >    This feature is **optional**;
   >    if you don’t see it in the main menu...

   (The Time Accounting dialog is not shown in the main menu;
   it is shown when updating a ticket.)

This commit fixes all instances of both of these problems.
It does not update the .mo and .po localization files.

* Demote "🤔 Huh? I don’t see..." notes

Certain pages for "optional features"
(e.g., live chat, CTI integration, knowledge base)
contain a note like the one below:

> .. note:: **🤔 Huh? I don’t see “Customer Chat” in the menu...**
>
>    This feature is **optional**;
>    if you don’t see it in the main menu,
>    that means your administrator hasn’t enabled it yet.
>    Administrators can learn more
>    `here <https://admin-docs.zammad.org/en/latest/channels-chat.html>`_.

Originally, this note was always placed at the very top of the page.
This commit moves all such notes
below their page's introductory screenshot,
on the rationale that readers should know _what we're talking about_
before learning _why it's not on their systems._

* Fix broken link to admin docs

The System Notifications page in the Zammad admin documentation
was moved on 7 May 2020 as part of that repo's PR #48[0] / efb7e9c.[1]

These user docs contained a reference to that page
which was not updated, and thus has been broken since then.
This commit fixes that broken link.

[0]: zammad/zammad-admin-documentation#48
[1]: zammad/zammad-admin-documentation@efb7e9c

* Move Advanced > Security & Encryption to Extras > Secure Email

This commit contains two changes:

1. Renaming "Security & Encryption" to "Secure Email".

   "Security and encryption" are two broad subjects
   that encompass a lot of considerations beyond S/MIME.
   "Security" could mean, e.g.,
   password and authentication policies,
   responsible stewardship of customer data, etc.

   "Secure email" more precisely captures what the page discusses.

2. Moving the S/MIME page from "Advanced" to "Extras".

   The "Advanced" section should be reserved for obscure features
   or user flows that are too complicated to introduce to beginners--
   in other words, the kind of things that would make someone
   a "power user".

   Since S/MIME is just a one-click option,
   it belongs better under "Extras".

* QA/Rewrite Secure Email page

* Match image filepaths with their articles

* Compress image assets

Co-authored-by: Ryan Lue <hello@ryanlue.com>
  • Loading branch information
@MrGeneration @rlue
MrGeneration and rlue committed Jun 19, 2020
1 parent ff8aef8 commit 00d5e3c
Show file tree
Hide file tree
Showing 18 changed files with 265 additions and 61 deletions.
10 changes: 10 additions & 0 deletions _static/theme/theme_overrides.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
.wy-table-responsive table td {
white-space: normal !important;
}

.wy-table-responsive table td img {
display: block;
margin-left: auto;
margin-right: auto;
width: 50%;
}
11 changes: 4 additions & 7 deletions advanced/text-modules.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,8 @@ Text modules on ticket creation
You can use text modules on ticket creation as well. On ticket creation, our :ref:`ticket_templates` might get handy too.


Changing text modules
^^^^^^^^^^^^^^^^^^^^^

For changing text modules, you need to have the permission to do so.
Please refer to our `Admin-Documentation <https://admin-docs.zammad.org/en/latest/manage-text-modules.html>`_ for further information.


Customizing text modules
^^^^^^^^^^^^^^^^^^^^^^^^

Administrators can learn more about customizing text modules
`here <https://admin-docs.zammad.org/en/latest/manage-text-modules.html>`_.
12 changes: 7 additions & 5 deletions advanced/time-accounting.rst
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,6 @@
Time Accounting
===============

.. note:: **🤔 Huh? I don’t see a “Time Accounting” dialog...**

This feature is **optional**; if you don’t see it in the main menu, that
means it’s not enabled yet. See the `admin documentation <https://admin-docs.zammad.org/en/latest/manage-time-accounting.html>`_ for details.

Zammad supports detailed time accounting
to help administrators keep track of how much time you spend
on any given ticket, customer or client organization.
Expand All @@ -19,3 +14,10 @@ on any given ticket, customer or client organization.
Enter how much time you spent on it
(in minutes, or whichever unit of time all your other colleagues are using).

.. note:: **🤔 Huh? I don’t see a “Time Accounting” dialog...**

This feature is **optional**;
if you don’t see it whenever you update a ticket,
that means your administrator hasn’t enabled it yet.
Administrators can learn more
`here <https://admin-docs.zammad.org/en/latest/manage-time-accounting.html>`_.
20 changes: 17 additions & 3 deletions conf.py
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
import sys
import os
import time

import sphinx_rtd_theme
import time

html_logo = "images/zammad_logo_70x61.png"
html_favicon = "images/favicon.ico"
Expand All @@ -19,5 +17,21 @@
gettext_compact = False
language = "en"

html_theme = "sphinx_rtd_theme"
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_static_path = ['_static']

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
# Override default css to solve issues (e.g. width, overflows)
def setup(app):
app.add_css_file('theme/theme_overrides.css')
else:
# Override default css to solve issues (e.g. width, overflows)
html_context = {
'css_files': [
'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
'_static/theme/theme_overrides.css'
],
}
13 changes: 8 additions & 5 deletions extras/caller-log.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,20 @@

View and manage call logs from the **phone** panel.

.. note:: **🤔 Huh? I don’t see “Phone” in the menu...**

This feature is **optional**; if you don’t see it in the main menu, that
means it’s not enabled yet. See the `admin documentation <https://admin-docs.zammad.org/en/latest/system-integrations.html#integrations-for-phone-systems>`_ for details.

.. figure:: /images/extras/phone.jpg
:alt: Sample view of Caller Log
:align: center

Enable the **Phone** panel to receive notifications for incoming calls.

.. note:: **🤔 Huh? I don’t see “Phone” in the menu...**

This feature is **optional**;
if you don’t see it in the main menu,
that means your administrator hasn’t enabled it yet.
Administrators can learn more
`here <https://admin-docs.zammad.org/en/latest/system-integrations.html#integrations-for-phone-systems>`_.

.. hint::
🏢 The caller log shows all incoming and outgoing calls **for the entire team**.

Expand Down
62 changes: 33 additions & 29 deletions extras/chat.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,38 +3,42 @@

Talk to customers in real time from the **customer chat** panel.

.. note:: **🤔 Huh? I don’t see “Customer Chat” in the menu...**

This feature is **optional**; if you don’t see it in the main menu, that
means it’s not enabled yet. See the `admin documentation <https://admin-docs.zammad.org/en/latest/channels-chat.html>`_ for details.

.. figure:: /images/extras/chat.jpg
:alt: Sample view of Customer Chat
:align: center

+---------------------------------------------------------------------------+
| Chat controls |
+===========================+===============================================+
| **1. On/Off** | Enable/disable the chat panel. |
| | (When enabled, you will receive notifications |
| | for incoming chats.) |
+---------------------------+-----------------------------------------------+
| **2. Waiting Customers** | Lists customers awaiting an agent for chat. |
| | **Click to answer a pending chat request.** |
+---------------------------+-----------------------------------------------+
| **3. Chatting Customers** | Lists customers currently in an ongoing chat |
| | session. |
+---------------------------+-----------------------------------------------+
| **4. Active Agents** | Lists all agents with chat enabled. |
+---------------------------+-----------------------------------------------+
| **5. Settings** | Click for chat configuration options (*e.g.,* |
| | auto-greetings and maximum number of |
| | simultaneous chats). |
+---------------------------+-----------------------------------------------+
| **6. Count badge** | Displays the number of users in each section. |
+---------------------------+-----------------------------------------------+
| **7. Info card** | Hover over for detailed information about the |
| | users in each section. |
+---------------------------+-----------------------------------------------+

.. note:: **🤔 Huh? I don’t see “Customer Chat” in the menu...**

Enable the chat panel to be notified when customers are waiting to chat.

+---------------------------------------------------------------------------+
| Chat controls |
+===========================+===============================================+
| **1. On/Off** | Enable/disable the chat panel. |
+---------------------------+-----------------------------------------------+
| **2. Waiting Customers** | Lists customers awaiting an agent for chat. |
| | **Click to answer a pending chat request.** |
+---------------------------+-----------------------------------------------+
| **3. Chatting Customers** | Lists customers currently in an ongoing chat |
| | session. |
+---------------------------+-----------------------------------------------+
| **4. Active Agents** | Lists all agents with chat enabled. |
+---------------------------+-----------------------------------------------+
| **5. Settings** | Click for chat configuration options (*e.g.,* |
| | auto-greetings and maximum number of |
| | simultaneous chats). |
+---------------------------+-----------------------------------------------+
| **6. Count badge** | Displays the number of users in each section. |
+---------------------------+-----------------------------------------------+
| **7. Info card** | Hover over for detailed information about the |
| | users in each section. |
+---------------------------+-----------------------------------------------+
This feature is **optional**;
if you don’t see it in the main menu,
that means your administrator hasn’t enabled it yet.
Administrators can learn more
`here <https://admin-docs.zammad.org/en/latest/channels-chat.html>`_.

.. warning:: If all agents have the chat panel disabled, customers will **not**
be able to initiate a chat.
Expand Down
23 changes: 13 additions & 10 deletions extras/knowledge-base.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,25 @@

Manage, edit, and reorganize knowledge base articles from the **knowledge base** panel.

.. figure:: /images/extras/knowledge-base-preview.png
:alt: Knowledge Base Preview Mode
:align: center

The knowledge base panel begins in **Preview Mode**.
With some small exceptions,
Preview Mode shows what the published knowledge base will look like.

.. note:: **🤔 Huh? I don’t see “Knowledge Base” in the menu...**

This feature is **optional**; if you don’t see it in the main menu, that
means it’s not enabled yet. See the `admin documentation <https://admin-docs.zammad.org/en/latest/manage-knowledge-base.html>`_ for details.
This feature is **optional**;
if you don’t see it in the main menu,
that means your administrator hasn’t enabled it yet.
Administrators can learn more
`here <https://admin-docs.zammad.org/en/latest/manage-knowledge-base.html>`_.

Getting Started
---------------

.. figure:: /images/extras/knowledge-base-preview.png
:alt: Knowledge Base Preview Mode
:align: center

The knowledge base panel begins in **Preview Mode**.
With some small exceptions,
Preview Mode shows what the published knowledge base will look like.

.. figure:: /images/extras/knowledge-base-link-to-public.png
:alt: Knowledge Base Link to published knowledge base
:align: center
Expand Down
6 changes: 4 additions & 2 deletions extras/profile-and-settings.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,10 @@ Profile Settings
**Limit Groups** box to disable such notifications on a per-group basis.
(You will continue to receive notifications for your own tickets.)

Consult the `admin documentation <https://admin-docs.zammad.org/en/latest/manage-trigger.html#other-notifications>`_
for details on how to customize these email notifications.
.. hint:: The contents of these email notifications
can be customized on self-hosted installations.
Administrators can learn more
`here <https://admin-docs.zammad.org/en/latest/manage/trigger/system-notifications.html>`_.

:Out of Office:

Expand Down

0 comments on commit 00d5e3c

Please sign in to comment.