Raise Admin-Docs to Zammad 3.2 state - #38
Merged
Merged
Conversation
This introduces our new group-dependent text modules. Besides, I removed a wrong text part that claimed that text modules would be available within Triggers (they are not).
This will satisfy issue #19
During by enhancement trip I thought that the overview of this page wasn't that good. This commit tries to solve this. It also fixes strange picture usuage which might lead to confusion. Corrected a small mistake that stated all users could change overview settings, while only agents can do so globally.
Other wise we won't find the SAML docs :)
Simply a small hint on the branches and what would be the best way to create a PR :)
HUGE thank you goes to Ben (https://github.com/peacepenguin) for all this amazing work! * adding information about group-dependent text modules This introduces our new group-dependent text modules. Besides, I removed a wrong text part that claimed that text modules would be available within Triggers (they are not). * Added performance hint for overviews This will satisfy issue #19 * Enhance overview of overview-documentation During by enhancement trip I thought that the overview of this page wasn't that good. This commit tries to solve this. It also fixes strange picture usuage which might lead to confusion. Corrected a small mistake that stated all users could change overview settings, while only agents can do so globally. * add saml docs * add saml docs image * adding saml documentation to security-settings page Other wise we won't find the SAML docs :) * heading marker adjustments * optical adjustments
This is a slight rework of Zammads object docs. It also introduces the new link template, but still lacks some fancy phrases and maybe even a variable doc.
This commit introduces an initial pre-version of future system variable reference that can be referenced all over the docs.
This will satisfy Issue zammad/zammad#2103 .
The variable list now contains sample data.
As suggested my Johannas within #35
This is going to address issu e #12 some day
Mainly affects navigation to behave better
This will satisfy issue #12
Tables where missing "s
ReStructuredText provides many ways to create internal links
(i.e., cross-referencing specific locations throughout a project).
The two most common ones are :doc: (for linking to a specific page) and
:ref: (for linking to any arbitrary location).
:ref: requires you to create a destination marker
somewhere in the project, like so:
.. foo::
so that it can be linked thusly:
:ref:`foo`
:doc:, on the other hand, simply takes the path of a page in the
project, and requires no additional marker to be added anywhere:
:doc:`/path/to/page`
Prior to this commit, there were many :ref: links that simply pointed to
the top of a target page. :doc: works just as well for this purpose,
so this commit replaces all those instances of :ref: with :doc:.
Originally, we had a docs page for "Settings in Tickets" which referred the ticket composer settings dialog. This page had no good place in the TOC (it was originally placed under the "Channels > Email" page), and the name was confusing (since we already have a "Settings > Ticket" page). This commit renames it to "Composer Settings" and places it under a new TOC section, "Misc".
At compile time (i.e., when running `make html`),
the ReStructuredText compiler emits warnings for syntax errors:
/zammad-admin-documentation/system-monitoring.rst:15: WARNING: Unexpected indentation.
/zammad-admin-documentation/system-monitoring.rst:19: WARNING: Unexpected indentation.
/zammad-admin-documentation/system-variables/config.rst:2: WARNING: Title underline too short.
This commit fixes all such syntax errors,
resulting in a clean compilation process.
Python convention (by which I mean the style guide
for official Python language documentation)
is to use three spaces for indentation in ReStructuredText files.
This is not a strict requirement of RST syntax[0],
but it produces a clean visual structure for RST's directive syntax:
.. note:: Lorem ipsum dolor
sit amet consectetur
In the case of lists, however, two spaces look better:
- Lorem ipsum dolor
sit amet consectetur
but in all other cases, we use three spaces for maximum consistency.
This commit replaces all indentation according to the rules above.
[0]: https://stackoverflow.com/questions/48311159
This commit was made purely for stylistic consistency.
This commit fixes RST syntax for certain `image::` directives. It was not strictly necessary, as the compiler doesn't raise an error in these cases, but was done for consistency within the codebase.
The existing docs contained many instances of German-style hyphens and
capitalization. In English, capitalization is reserved for titles and
proper nouns.
Of course, in technical writing, sometimes it's appropriate to
capitalize words that refer to elements on the screen, such as:
> When you're finished writing your message, click "Submit".
In these cases, the screen element ("Submit") should be emphasized with
additional styling, such as quotation marks, italics, or boldfaced
lettering.
(I don't have a source for this, unfortunately, but I would argue that
it's more than my personal opinion.)
This commit doesn't add any such styling to these cases, but it does
fix capitalization where appropriate.
Hyphens are used sparingly, and the rules are confusing. "Auto-reply" is
okay, but "API token" is not (because "API" is its own word, but "auto"
is not). "Email-related" is also okay, because it forms one single
adjective.
rlue
approved these changes
Dec 9, 2019
rlue
left a comment
rlue
left a comment
Contributor
There was a problem hiding this comment.
My commits add a ton more changes, mostly related to:
- RST syntax,
- removing trailing whitespace,
- making indentation consistent,
- making internal links consistent,
- reorganizing the file structure of the repo, or
- fixing German grammatical/capitalization patterns to English.
I have not looked over all the language in great detail, but thought it was important to start from that foundation before moving onto editing content.
In general, I think the language is good enough, and in most cases, could be improved by making it shorter. I am happy to QA that aspect of the admin docs next time.
rlue
pushed a commit
that referenced
this pull request
Jun 19, 2020
* adding information about group-dependent text modules This introduces our new group-dependent text modules. Besides, I removed a wrong text part that claimed that text modules would be available within Triggers (they are not). * Added performance hint for overviews This will satisfy issue #19 * Enhance overview of overview-documentation During by enhancement trip I thought that the overview of this page wasn't that good. This commit tries to solve this. It also fixes strange picture usuage which might lead to confusion. Corrected a small mistake that stated all users could change overview settings, while only agents can do so globally. * add saml docs * add saml docs image * WIP: Usuage of Macros * adding saml documentation to security-settings page Other wise we won't find the SAML docs :) * heading marker adjustments * optical adjustments * update Readme with protected branch note Simply a small hint on the branches and what would be the best way to create a PR :) * Rework of objects This is a slight rework of Zammads object docs. It also introduces the new link template, but still lacks some fancy phrases and maybe even a variable doc. * Initial system variable commit This commit introduces an initial pre-version of future system variable reference that can be referenced all over the docs. * added hints / references to system variables * update object detail view to show current function as well * Rework and finish for system objects This will satisfy Issue zammad/zammad#2103 . * finish ticket system-variables The variable list now contains sample data. * System variable values for config variables * added values for article variables * description text for ticket article variables * add Telegram hint for file sizes See issue: zammad/zammad#2289 * add hint for system variables to text modules As suggested my Johannas within #35 * WIP: Refactoring E-Mail channel structure * WIP: E-Mail-Settings This is going to address issu e #12 some day * WIP: E-Mail-Settings * E-Mail channel structual doc changes Mainly affects navigation to behave better * Finish E-Mail-Settings tab This will satisfy issue #12 * typo fixing for variable tables Tables where missing "s * cherrypick email-channel commit for 2FA gmail This commits ensures not to loose information on 2FA gmail. * small rework of signature documentation Mainly optical changes * Finish Settings in Ticket hint This helps to cover these fairly hidden settings and describes what they do/mean. * Rework ticket section This is mainly an optical rewrite, but also changes some wordings. * Add remark about technical size limitations of telegram messages * fix typo Link was broken * added values for current user variables This finishes the variable part of the documentation (yay) * Updated SAML docs to contain automatic linking reference This helps users to find the automatic account linking option easier. :-) * added missing picture for github authentication * corrected typo has stated by Johanna. :) * Replace :ref: with :doc: wherever possible ReStructuredText provides many ways to create internal links (i.e., cross-referencing specific locations throughout a project). The two most common ones are :doc: (for linking to a specific page) and :ref: (for linking to any arbitrary location). :ref: requires you to create a destination marker somewhere in the project, like so: .. foo:: so that it can be linked thusly: :ref:`foo` :doc:, on the other hand, simply takes the path of a page in the project, and requires no additional marker to be added anywhere: :doc:`/path/to/page` Prior to this commit, there were many :ref: links that simply pointed to the top of a target page. :doc: works just as well for this purpose, so this commit replaces all those instances of :ref: with :doc:. * QA E-Mail docs * Reorganize "Channels > Email" subtree * Create "Misc" TOC section for Composer Settings docs Originally, we had a docs page for "Settings in Tickets" which referred the ticket composer settings dialog. This page had no good place in the TOC (it was originally placed under the "Channels > Email" page), and the name was confusing (since we already have a "Settings > Ticket" page). This commit renames it to "Composer Settings" and places it under a new TOC section, "Misc". * Fix RST syntax errors At compile time (i.e., when running `make html`), the ReStructuredText compiler emits warnings for syntax errors: /zammad-admin-documentation/system-monitoring.rst:15: WARNING: Unexpected indentation. /zammad-admin-documentation/system-monitoring.rst:19: WARNING: Unexpected indentation. /zammad-admin-documentation/system-variables/config.rst:2: WARNING: Title underline too short. This commit fixes all such syntax errors, resulting in a clean compilation process. * Remove trailing whitespace from all files * Remove macOS .DS_Store metadata file from repo * Fix RST indentation Python convention (by which I mean the style guide for official Python language documentation) is to use three spaces for indentation in ReStructuredText files. This is not a strict requirement of RST syntax[0], but it produces a clean visual structure for RST's directive syntax: .. note:: Lorem ipsum dolor sit amet consectetur In the case of lists, however, two spaces look better: - Lorem ipsum dolor sit amet consectetur but in all other cases, we use three spaces for maximum consistency. This commit replaces all indentation according to the rules above. [0]: https://stackoverflow.com/questions/48311159 * Downcase all directives This commit was made purely for stylistic consistency. * Fix instances of hanging '::' This commit fixes RST syntax for certain `image::` directives. It was not strictly necessary, as the compiler doesn't raise an error in these cases, but was done for consistency within the codebase. * Replace 'E-Mail' with 'email' * Fix German-style hyphens and capitalization The existing docs contained many instances of German-style hyphens and capitalization. In English, capitalization is reserved for titles and proper nouns. Of course, in technical writing, sometimes it's appropriate to capitalize words that refer to elements on the screen, such as: > When you're finished writing your message, click "Submit". In these cases, the screen element ("Submit") should be emphasized with additional styling, such as quotation marks, italics, or boldfaced lettering. (I don't have a source for this, unfortunately, but I would argue that it's more than my personal opinion.) This commit doesn't add any such styling to these cases, but it does fix capitalization where appropriate. Hyphens are used sparingly, and the rules are confusing. "Auto-reply" is okay, but "API token" is not (because "API" is its own word, but "auto" is not). "Email-related" is also okay, because it forms one single adjective. * QA README * QA Telegram docs * QA references to system-variables page * QA SAML docs * QA Ticket Settings docs * QA System Variables docs * Reorganize directory structure to reflect TOC * Remove unused 'Roles' draft doc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Hey Johanna,
can you please have a look and QA the upcoming changes?
There's a lot reworks inside, but as far as I'm aware we also have all 3.1 to 3.2 changes covered.
Also E-Mail Channel is complete and we're introducing system variables. :>
Thanks!