code review

dashboard/src/components/docs/Moderation.vue

@@ -1,114 +1,152 @@
 <template>
   <div>
-    <h1>Moderation</h1>
+    <header>
+      <h1>Moderation</h1>
+      <p>
+        Moderation in Zeppelin is multi-layered. On top of typical actions such
+        as warning, muting, kicking, and banning, Zeppelin allows moderators to
+        utilise flags; create alerts; set thresholds; and act as others.
+      </p>
+      <p>
+        This guide explains the options available in the
+        <router-link to="/docs/plugins/modactions"> Mod actions</router-link>
+        plugin. To best use this guide, read the default configuration of the
+        Mod actions plugin alongside this. This plugin does
+        <strong>not</strong> cover muting members, please see the
+        <router-link to="/docs/plugins/mutes">Mutes</router-link> plugin.
+      </p>
+      <p>
+        Please ensure you understand how
+        <router-link to="/docs/plugins/plugin-configuration">plugin
+          configuration</router-link> and
+        <router-link to="/docs/configuration/permissions">plugin
+          permissions </router-link>work before reading this guide since
+        the configs defined here rely on your these concepts.
+      </p>
+    </header>
+
+    <h2>Moderation Commands</h2>
     <p>
-      Moderation in Zeppelin is multi-layered, with 'typical' actions such as warning, muting, kicking, banning,
+      So that your moderators may use Zeppelin moderation, you must define the
-      etc. Featuring flags, moderation advances to allow for alerts, thresholds, acting as others, and the creation of
+      moderator role Id in the config and assign it a level (50).
-      cases for context (right-click) actions.
+      <CodeBlock code-lang="yaml" trim="start">
+        levels:
+          "PRETEND-ROLE-ID": 50 # Mod
+
+        plugins:
+        ...
+      </CodeBlock>
     </p>
     <p>
-      This guide will be expanded in the future. For now it covers how to setup the
+      Each moderation command has a permission attached to it, so if your
-      <router-link to="/docs/plugins/modactions"> Mod Actions plugin</router-link>.
+      server has a hierarchical structure then you will be able to scope
+      these permissions by referencing the plugins permissions page.
     </p>
 
     <h2>Sanction Notifications</h2>
-    <p>These first config options define how Zeppelin will interact with the users sanctioned.</p>
+    <p>These config options define how Zeppelin will interact with the
+      members it sanctions (warns, kicks, bans).</p>
 
     <h3>DM Values</h3>
     <p>
-      The values `dm_on_warn`, `dm_on_kick`, and `dm_on_ban` determine whether a user will be notified of their sanctions
+      The values <code>dm_on_warn</code>, <code>dm_on_kick</code>, and
-      through DMs. Ignoring privacy settings, setting these to `true` will notify the user, and `false` keeps them in the
+      <code>dm_on_ban</code> determine whether a member will be notified of
-      dark. Note: `tempban` actions take the `ban` configuration.
+      their sanctions through DMs. Ignoring privacy settings, setting these to
+      <code>true</code> will notify the member. Temporary banning uses the
+      ban configuration.
     </p>
 
     <h3>Channel Values</h3>
     <p>
-      The other set of notifying options `message_on_warn`, `message_on_kick`, and `message_on_ban` are similar to their
+      An alternative way to notify members about sanctions is through
-      `DM` counterparts, but, taking the value of `message_channel` they notify a channel instead. Note: `tempban` actions
+      mentioning them in a message sent in a channel. To enable this feature,
-      take the `ban` configuration.
+      set <code>message_on_warn</code>, <code>message_on_kick</code>, and
+      and <code>message_on_ban</code> to true (enabling them), then assign a
+      <code>message_channel</code>.
     </p>
 
-    <h4>Notifying messages</h4>
+    <h3>Notifying messages</h3>
     <p>
-      Both of these notifying options take the same message templates defined in `warn_message`, `kick_message`, and
+      This is how you control the exact wording the member receives. You can
-      `ban_message`. In the official documentation, you will see these written as one line, you can make the messages
+      adjust the wording per sanction type. These variables are
-      multi-line like so:
+      <code>warn_message</code>, <code>kick_message</code>, and
-        <CodeBlock code-lang="yaml">
+      <code>ban_message</code>. Please remember that YAML supports mutli-line
-          plugins:
+      strings, this is how you can write newlines in your messages. Notably,
-            mod_actions:
+      temporarily banning a member permits the inclusion of the
-              config:
+      <code>banTime</code> variable through <code>tempban_message</code>.
-                warn_message: |-
-                  I am a
-                  multi-line message!
-        </CodeBlock>
-
-      However, the `tempban` action has its own message option that can be defined under `tempban_message`, it comes
-      with an exciting new variable: `banTime`.
     </p>
 
+    <h3>Summary Example</h3>
+    Employing what we have learnt so far, we can write a configuration that:
+      <ul>
+        <li>Alerts members of their warns in a channel, instead of DMs.</li>
+        <li>Alerts members of kicks and bans in their DMs.</li>
+        <li>Makes use of multi-line strings to prepare a tidy message.</li>
+        <li>Includes the remaining ban time if a ban was temporary.</li>
+      </ul>
+    <CodeBlock code-lang="yaml" trim="start">
+      plugins:
+        mod_actions:
+          config:
+            dm_on_warn: false
+            message_on_warn: true
+            message_channel: "PRETEND-CHANNEL-ID"
+
+            dm_on_kick: true
+
+            dm_on_ban: true
+            tempban_message: |-
+              Dear {user.username},
+
+              As a result of {reason}, you have been banned from {guildName}
+              for {banTime}. We welcome you back provided you do not do this
+              again.
+    </CodeBlock>
+
     <h2>Alerts</h2>
     <p>
-      Alerts are a nifty way for your mod-team to be notified of actors trying to evade sanctions by leaving and
+      Alerts are a nifty way for moderators to be notified of members trying to
-      re-joining your server. Define the channel in `alert_channel` and set `alert_on_rejoin` to `true`.
+      evade sanctions by promptly leaving and rejoining your server. To enable
+      this feature, assign a channel in <code>alert_channel</code> and enable
+      <code>alert_on_rejoin</code>.
     </p>
+    <CodeBlock code-lang="yaml" trim="start">
+      plugins:
+        mod_actions:
+          config:
+            alert_on_rejoin: true
+            alert_channel: "PRETEND-CHANNEL-ID"
+    </CodeBlock>
 
     <h2>Thresholds</h2>
     <p>
-      Thresholds are useful for alerting moderators if a user is about to exceed a pre-determined number of cases.
+      Thresholds alert moderators if a member is about to exceed a
-      This can be used to make your mod team consider whether harsher action is necessary. Define the threshold in
+      predetermined number of cases, prompting moderators to consider whether
-      `warn_notify_threshold`, adjust the message under `warn_notify_message`, and enable `warn_notify_enabled`.
+      alternative (harsher) action could be taken. To enable thresholds,
+      assign the threshold as <code>warn_notify_threshold</code>, adjust the
+      message under <code>warn_notify_message</code>, and enable
+      <code>warn_notify_enabled</code>.
+    </p>
+    <p>
+      Write your config cleverly, check the default values for
+      <code>warn_notify_threshold</code> and <code>warn_notify_message</code>,
+      if these are acceptable then all you need to do is enable
+      <code>warn_notify_enabled</code>.
     </p>
 
     <h2>Ban Message Deletion</h2>
     <p>
-      You can adjust the day's worth of messages Zeppelin deletes under the `ban_delete_message_days` option. Do not
+      When a member is banned, Zeppelin automatically deletes the last day of
-      append your input with 'd'.
+      message history. You can extend this through the
-    </p>
+      <code>ban_delete_message_days</code> option.
-
-    <h2>Moderation Commands</h2>
-    <p>
-      Before reading this, you should read the
-      <router-link to="/docs/configuration/permissions">Permission's page</router-link> before continuing to set up this
-      plugin.
-
-      Zeppelin has 5 core commands, `note`, `warn`, `mute`, `kick`, and `ban`; with `unban`, `view`, and `addcase`
-      making 8. By default, these are disabled for users levelled 0, and enabled for users level 50 and above.
-
-      This guide does not go into detail about how to use them at the moment, you can read a different guide for that
-      <a href="https://docs.google.com/presentation/d/e/2PACX-1vQTFZW4NiJicngfAv36tLlWG5XjktVyZhljekOkzUyzsktwcNCH_Zm82Dm3r1c7S7vKOArJ6XIO5azC/pub?start=true&loop=false&delayms=60000&slide=id.gc6f9e470d_0_0"> here.</a>
-
-      The
-      <a href="https://zeppelin.gg/docs/plugins/mod_actions/configuration"> default configuration</a>
-      outlines what permissions are available for those level 50 & level 100, this guide will explain how to adjust
-      those permissions with overrides.
-
-      In the example below, users levelled 50 and above are now able to hide cases.
-
-      <Expandable class="wide">
-        <template v-slot:title>Click to view example</template>
-        <template v-slot:content>
-          <CodeBlock code-lang="yaml">
-            levels:
-              "807693394393956422": 50 #Mod
-
-            plugins:
-              mod_actions:
-                overrides:
-                  - level: ">=50"
-                    config:
-                      can_hidecase: true
-          </CodeBlock>
-        </template>
-      </Expandable>
     </p>
   </div>
 </template>
 
 <script lang="ts">
-import CodeBlock from "./CodeBlock.vue";
+  import CodeBlock from "./CodeBlock.vue";
-import Expandable from "../Expandable.vue";
 
-export default {
+  export default {
-  components: {Expandable, CodeBlock },
+    components: { CodeBlock },
-};
+  };
 </script>