From b5a0483603333e3785ad2823c9ee22fa369b2c7a Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Thu, 12 Oct 2017 16:58:12 +0100 Subject: [PATCH 01/15] Update nav --- docs/_data/nav.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/_data/nav.yaml b/docs/_data/nav.yaml index eeb7c2ebc..9a205e8fe 100644 --- a/docs/_data/nav.yaml +++ b/docs/_data/nav.yaml @@ -17,6 +17,10 @@ items: children: - title: How Talk Works url: /how-talk-works/ + - title: Commenter Features + url: /commenter-features/ + - title: Moderator Features + url: /moderator-features/ - title: Trust url: /trust/ - title: Toxic Comments From 06d0da9286ec05a060653742e525757a2a30f7fe Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Fri, 13 Oct 2017 15:50:13 +0100 Subject: [PATCH 02/15] Reorganize file order and reinstate h2s --- docs/_docs/02-01-required-configuration.md | 12 +-- docs/_docs/02-02-advanced-configuration.md | 82 +++++++++---------- ... => 03-01-product-guide-how-talk-works.md} | 0 .../03-02-product-guide-commenter-features.md | 4 + .../03-03-product-guide-moderator-features.md | 4 + ...-trust.md => 03-04-product-guide-trust.md} | 0 ... => 03-05-product-guide-toxic-comments.md} | 0 ...-overview.md => 04-01-plugins-overview.md} | 0 ...lt-plugins.md => 04-02-default-plugins.md} | 36 ++++---- ...plugins.md => 04-03-additional-plugins.md} | 20 ++--- ...gin-recipes.md => 04-04-plugin-recipes.md} | 8 +- docs/_sass/talk.scss | 3 - 12 files changed, 85 insertions(+), 84 deletions(-) rename docs/_docs/{04-01-product-guide-how-talk-works.md => 03-01-product-guide-how-talk-works.md} (100%) create mode 100644 docs/_docs/03-02-product-guide-commenter-features.md create mode 100644 docs/_docs/03-03-product-guide-moderator-features.md rename docs/_docs/{04-02-product-guide-trust.md => 03-04-product-guide-trust.md} (100%) rename docs/_docs/{04-03-product-guide-toxic-comments.md => 03-05-product-guide-toxic-comments.md} (100%) rename docs/_docs/{03-01-plugins-overview.md => 04-01-plugins-overview.md} (100%) rename docs/_docs/{03-02-default-plugins.md => 04-02-default-plugins.md} (92%) rename docs/_docs/{03-03-additional-plugins.md => 04-03-additional-plugins.md} (93%) rename docs/_docs/{03-04-plugin-recipes.md => 04-04-plugin-recipes.md} (95%) diff --git a/docs/_docs/02-01-required-configuration.md b/docs/_docs/02-01-required-configuration.md index 84a7236db..dc09a1707 100644 --- a/docs/_docs/02-01-required-configuration.md +++ b/docs/_docs/02-01-required-configuration.md @@ -19,7 +19,7 @@ If you've already configured your application with the required configuration, you can further customize it's behavior by applying [Advanced Configuration]({{ "/advanced-configuration/" | relative_url }}). -### TALK_MONGO_URL +## TALK_MONGO_URL The database connection string for the MongoDB database. This usually takes the form of: @@ -31,7 +31,7 @@ TALK_MONGO_URL=mongodb://:@:` component of the [TALK_ROOT_URL]({{ "/configuration/#talk_root_url" | relative_url }}){: .param}. @@ -361,7 +361,7 @@ Then all the routes for the API will be expecting to be hit on `/talk/`, such as can perform the path stripping when serving an upstream proxy, but some CDN's cannot. You would use this option in the latter situation. -### TALK_SMTP_EMAIL +## TALK_SMTP_EMAIL The email address to send emails from using the SMTP provider in the format: @@ -371,23 +371,23 @@ TALK_SMTP_EMAIL="The Coral Project" Including the name and email address. -### TALK_SMTP_HOST +## TALK_SMTP_HOST The domain for the SMTP provider that you are using. -### TALK_SMTP_PASSWORD +## TALK_SMTP_PASSWORD The password for the SMTP provider you are using. -### TALK_SMTP_PORT +## TALK_SMTP_PORT The port for the SMTP provider that you are using. -### TALK_SMTP_USERNAME +## TALK_SMTP_USERNAME The username of the SMTP provider you are using. -### TALK_STATIC_URI +## TALK_STATIC_URI Used to set the uri where the static assets should be served from. This is used when you want to upload the static assets through your build process to a @@ -395,14 +395,14 @@ service like Google Cloud Storage or Amazon S3 and you would then specify the CDN/Storage url. (Defaults to value of [TALK_ROOT_URL]({{ "/configuration/#talk_root_url" | relative_url }}){: .param}) -### TALK_THREADING_LEVEL +## TALK_THREADING_LEVEL Specify the maximum depth of the comment thread. (Default `3`) **Note that a high value for `TALK_THREADING_LEVEL` will result in large performance impacts.** -### TALK_WEBSOCKET_LIVE_URI +## TALK_WEBSOCKET_LIVE_URI Used to override the location to connect to the websocket endpoint to potentially another host. This should be used when you need to route websocket @@ -419,7 +419,7 @@ is `FALSE`, or the path component of **Warning: if used without managing the auth state manually, auth cannot be persisted due to browser restrictions.** -### TRUST_THRESHOLDS +## TRUST_THRESHOLDS Configure the reliability thresholds for flagging and commenting. (Default `comment:2,-1;flag:2,-1`) diff --git a/docs/_docs/04-01-product-guide-how-talk-works.md b/docs/_docs/03-01-product-guide-how-talk-works.md similarity index 100% rename from docs/_docs/04-01-product-guide-how-talk-works.md rename to docs/_docs/03-01-product-guide-how-talk-works.md diff --git a/docs/_docs/03-02-product-guide-commenter-features.md b/docs/_docs/03-02-product-guide-commenter-features.md new file mode 100644 index 000000000..8fde0f0ac --- /dev/null +++ b/docs/_docs/03-02-product-guide-commenter-features.md @@ -0,0 +1,4 @@ +--- +title: Commenter Features +permalink: /commenter-features/ +--- diff --git a/docs/_docs/03-03-product-guide-moderator-features.md b/docs/_docs/03-03-product-guide-moderator-features.md new file mode 100644 index 000000000..355c40a1c --- /dev/null +++ b/docs/_docs/03-03-product-guide-moderator-features.md @@ -0,0 +1,4 @@ +--- +title: Moderator Features +permalink: /moderator-features/ +--- diff --git a/docs/_docs/04-02-product-guide-trust.md b/docs/_docs/03-04-product-guide-trust.md similarity index 100% rename from docs/_docs/04-02-product-guide-trust.md rename to docs/_docs/03-04-product-guide-trust.md diff --git a/docs/_docs/04-03-product-guide-toxic-comments.md b/docs/_docs/03-05-product-guide-toxic-comments.md similarity index 100% rename from docs/_docs/04-03-product-guide-toxic-comments.md rename to docs/_docs/03-05-product-guide-toxic-comments.md diff --git a/docs/_docs/03-01-plugins-overview.md b/docs/_docs/04-01-plugins-overview.md similarity index 100% rename from docs/_docs/03-01-plugins-overview.md rename to docs/_docs/04-01-plugins-overview.md diff --git a/docs/_docs/03-02-default-plugins.md b/docs/_docs/04-02-default-plugins.md similarity index 92% rename from docs/_docs/03-02-default-plugins.md rename to docs/_docs/04-02-default-plugins.md index ab843f21b..aff17ebcc 100644 --- a/docs/_docs/03-02-default-plugins.md +++ b/docs/_docs/04-02-default-plugins.md @@ -16,7 +16,7 @@ Talk that are not enabled by default. You can enable these or disable these default plugins by consulting the [Plugins Overview]({{ "/plugins/" | relative_url }}) page. -### talk-plugin-auth +## talk-plugin-auth Source: [plugins/talk-plugin-auth](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-auth){:target="_blank"} @@ -24,7 +24,7 @@ Enables generic registration via an email address, a username, a password, and a password confirmation. To sync Talk auth with your own auth systems, you can use this plugin as a template. -### talk-plugin-facebook-auth +## talk-plugin-facebook-auth Source: [plugins/talk-plugin-auth](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-auth){:target="_blank"} @@ -34,12 +34,10 @@ Enables sign-in via Facebook via the server side passport middleware. Configuration: -{:.no_toc} - - [TALK_FACEBOOK_APP_ID]({{ "/configuration/#talk_facebook_app_id" | relative_url }}){:.param} (**required**) - See the existing documentation for the [TALK_FACEBOOK_APP_ID]({{ "/configuration/#talk_facebook_app_id" | relative_url }}){:.param}. - [TALK_FACEBOOK_APP_SECRET]({{ "/configuration/#talk_facebook_app_secret" | relative_url }}){:.param} (**required**) - See the existing documentation for the [TALK_FACEBOOK_APP_SECRET]({{ "/configuration/#talk_facebook_app_secret" | relative_url }}){:.param}. -### talk-plugin-featured-comments +## talk-plugin-featured-comments Source: [plugins/talk-plugin-featured-comments](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-featured-comments){:target="_blank"} @@ -47,14 +45,14 @@ Enables the ability for Moderators to feature and un-feature comments via the Stream and the Admin. Featured comments show in a first-place tab on the Stream if there are any featured comments on that story. -### talk-plugin-respect +## talk-plugin-respect Source: [plugins/talk-plugin-respect](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-respect){:target="_blank"} Enables a `respect` reaction button. Why a "respect" button, you ask? [Read more here](https://mediaengagement.org/research/engagement-buttons/). -### talk-plugin-comment-content +## talk-plugin-comment-content Source: [plugins/talk-plugin-comment-content](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-comment-content){:target="_blank"} @@ -62,7 +60,7 @@ Pluginizes the text of a comment to support custom treatment of this text. This plugin currently parses the given text to see if it contains a link, and makes them clickable. -### talk-plugin-ignore-user +## talk-plugin-ignore-user Source: [plugins/talk-plugin-ignore-user](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-ignore-user){:target="_blank"} @@ -70,20 +68,20 @@ Enables ability for users to ignore (or "mute") other users. If a user is ignored, you will not see any of their comments. You can un-ignore a user via the My Profile tab. -### talk-plugin-permalink +## talk-plugin-permalink Source: [plugins/talk-plugin-permalink](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-permalink){:target="_blank"} Enables a `Link` button that will provide a permalink to the comment that can be shared with others. -### talk-plugin-viewing-options +## talk-plugin-viewing-options Source: [plugins/talk-plugin-viewing-options](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-viewing-options){:target="_blank"} Pluginizes the sorting/viewing options for a comment stream. -### talk-plugin-sort-newest +## talk-plugin-sort-newest Source: [plugins/talk-plugin-sort-newest](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-newest){:target="_blank"} @@ -92,7 +90,7 @@ Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param} Provides a sort for the newest comments first. This isn't necessarily required as the default sort without options/plugins is newest first. -### talk-plugin-sort-oldest +## talk-plugin-sort-oldest Source: [plugins/talk-plugin-sort-oldest](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-oldest){:target="_blank"} @@ -100,7 +98,7 @@ Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param} Provides a sort for the newest comments first. -### talk-plugin-most-respected +## talk-plugin-most-respected Source: [plugins/talk-plugin-most-respected](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-most-respected){:target="_blank"} @@ -108,7 +106,7 @@ Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param}, Provides a sort for the comments with the most `respect` reactions first. -### talk-plugin-most-replied +## talk-plugin-most-replied Source: [plugins/talk-plugin-most-replied](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-most-replied){:target="_blank"} @@ -116,20 +114,20 @@ Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param} Provides a sort for the comments with the most replies first. -### talk-plugin-offtopic +## talk-plugin-offtopic Source: [plugins/talk-plugin-offtopic](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-offtopic){:target="_blank"} Allows the comment authors to tag their comment as `Off-Topic` which will add a visible badge on the frontend to other users that their comment is off-topic. -### talk-plugin-author-menu +## talk-plugin-author-menu Source: [plugins/talk-plugin-author-menu](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-author-menu){:target="_blank"} Pluginizes the author's name on hover. -### talk-plugin-member-since +## talk-plugin-member-since Source: [plugins/talk-plugin-member-since](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-member-since){:target="_blank"} @@ -137,14 +135,14 @@ Requires: [talk-plugin-author-menu](#talk-plugin-author-menu){:.param} Displays the date that the user was created as a `Member Since ${created_at}`. -### talk-plugin-moderation-actions +## talk-plugin-moderation-actions Source: [plugins/talk-plugin-moderation-actions](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-moderation-actions){:target="_blank"} Enables in-stream moderation so that Moderators can reject, approve comments, as well as ban users, directly from the comment stream. When [talk-plugin-featured-comments](#talk-plugin-featured-comments){:.param} is enabled -### talk-plugin-flag-details +## talk-plugin-flag-details Source: [plugins/talk-plugin-flag-details](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-flag-details){:target="_blank"} diff --git a/docs/_docs/03-03-additional-plugins.md b/docs/_docs/04-03-additional-plugins.md similarity index 93% rename from docs/_docs/03-03-additional-plugins.md rename to docs/_docs/04-03-additional-plugins.md index 9be7f1cd2..55ab1749b 100644 --- a/docs/_docs/03-03-additional-plugins.md +++ b/docs/_docs/04-03-additional-plugins.md @@ -11,13 +11,13 @@ Talk ships with several plugins that aren't enabled by default: These plugins can be enabled by consulting the [Plugins Overview]({{ "/plugins/" | relative_url }}) page. -### talk-plugin-like +## talk-plugin-like Source: [plugins/talk-plugin-like](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-like){:target="_blank"} Enables a `like` reaction button. -### talk-plugin-sort-most-liked +## talk-plugin-sort-most-liked Source: [plugins/talk-plugin-sort-most-liked](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-liked){:target="_blank"} @@ -25,13 +25,13 @@ Requires: [talk-plugin-viewing-options]({{ "/default-plugins/#talk-plugin-viewin Provides a sort for the comments with the most `like` reactions first. -### talk-plugin-love +## talk-plugin-love Source: [plugins/talk-plugin-love](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-love){:target="_blank"} Enables a `love` reaction button. -### talk-plugin-sort-most-loved +## talk-plugin-sort-most-loved Source: [plugins/talk-plugin-sort-most-loved](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-loved){:target="_blank"} @@ -39,7 +39,7 @@ Requires: [talk-plugin-viewing-options]({{ "/default-plugins/#talk-plugin-viewin Provides a sort for the comments with the most `love` reactions first. -### talk-plugin-remember-sort +## talk-plugin-remember-sort Source: [plugins/talk-plugin-remember-sort](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-remember-sort){:target="_blank"} @@ -47,7 +47,7 @@ Requires: [talk-plugin-viewing-options]({{ "/default-plugins/#talk-plugin-viewin Enables saving a user’s last sort selection as they browse other articles. -### talk-plugin-deep-reply-count +## talk-plugin-deep-reply-count Source: [plugins/talk-plugin-deep-reply-count](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-deep-reply-count){:target="_blank"} @@ -55,7 +55,7 @@ Enables counting of comments to include replies via a new graph edge. Not recommended for large installations as it will unreasonably reduce the query efficiency to compute this number. -### talk-plugin-slack-notifications +## talk-plugin-slack-notifications Source: [plugins/talk-plugin-slack-notifications](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-slack-notifications){:target="_blank"} @@ -70,12 +70,11 @@ Slack, if this isn't what you want, be sure to use the provided plugin as a recipe to further customize the behavior*. Configuration: -{:.no_toc} - `SLACK_WEBHOOK_URL` (**required**) - The webhook url that will be used to post new comments to. -### talk-plugin-toxic-comments +## talk-plugin-toxic-comments Source: [plugins/talk-plugin-toxic-comments](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-toxic-comments){:target="_blank"} @@ -85,7 +84,6 @@ threshold. For more information on what Toxic Comments are, check out the [Toxic Comments]({{ "/toxic-comments/" | relative_url }}) documentation. Configuration: -{:.no_toc} - `TALK_PERSPECTIVE_API_KEY` (**required**) - The API Key for Perspective. You can register and get your own key at [http://perspectiveapi.com/](http://perspectiveapi.com/){:target="_blank"}. @@ -97,7 +95,7 @@ Configuration: be processed before it will skip the toxicity analysis, parsed by [ms](https://www.npmjs.com/package/ms){:target="_blank"}. (Default `300ms`) -### talk-plugin-subscriber +## talk-plugin-subscriber Source: [plugins/talk-plugin-subscriber](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-subscriber){:target="_blank"} diff --git a/docs/_docs/03-04-plugin-recipes.md b/docs/_docs/04-04-plugin-recipes.md similarity index 95% rename from docs/_docs/03-04-plugin-recipes.md rename to docs/_docs/04-04-plugin-recipes.md index 6b76a54ca..019ff21e4 100644 --- a/docs/_docs/03-04-plugin-recipes.md +++ b/docs/_docs/04-04-plugin-recipes.md @@ -16,7 +16,7 @@ The following are the available recipes for use: {% include toc.html %} -### recipe-avatar +## recipe-avatar Source: [talk-recipes/tree/master/plugins/avatar](https://github.com/coralproject/talk-recipes/tree/master/plugins/avatar){:target="_blank"} @@ -24,7 +24,7 @@ Provides support for avatars hosted via third party, extends the User Model and provides UI on the client-side too. -### recipe-translations +## recipe-translations Source: [talk-recipes/tree/master/plugins/translations](https://github.com/coralproject/talk-recipes/tree/master/plugins/translations){:target="_blank"} @@ -32,7 +32,7 @@ Provides an example for overriding application text through the translation system. -### recipe-subscriber +## recipe-subscriber Source: [talk-recipes/tree/master/plugins/subscriber](https://github.com/coralproject/talk-recipes/tree/master/plugins/subscriber){:target="_blank"} @@ -41,7 +41,7 @@ Provides an example for adding `SUBSCRIBER` badges for users with the the auth system. -### recipe-author-name +## recipe-author-name Source: [talk-recipes/tree/master/plugins/author-name](https://github.com/coralproject/talk-recipes/tree/master/plugins/author-name){:target="_blank"} diff --git a/docs/_sass/talk.scss b/docs/_sass/talk.scss index 85e5f1c93..69e039951 100644 --- a/docs/_sass/talk.scss +++ b/docs/_sass/talk.scss @@ -41,9 +41,6 @@ h2, h3, h4 { } article.configuration { - h2 { - font-weight: bolder; - } h2, .toc { @extend .param; From 5dd08d84e5f5a8694bf6679960e50f96b856c50c Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Fri, 13 Oct 2017 16:48:21 +0100 Subject: [PATCH 03/15] Added Commenter Features section --- .../03-02-product-guide-commenter-features.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) diff --git a/docs/_docs/03-02-product-guide-commenter-features.md b/docs/_docs/03-02-product-guide-commenter-features.md index 8fde0f0ac..81ec5128d 100644 --- a/docs/_docs/03-02-product-guide-commenter-features.md +++ b/docs/_docs/03-02-product-guide-commenter-features.md @@ -2,3 +2,141 @@ title: Commenter Features permalink: /commenter-features/ --- + +## Signing up for Talk + +There are 2 ways that newsrooms can support signup/login functionality with Talk: + +Use Talk’s auth plugin out of the box (supports account registration with username and password, as well as features like forgot password) + +Create their own auth plugin (you can use ours as a template) to integrate with your own auth systems + +We also provide a Facebook auth plugin that supports logging in with Facebook (you must provide your own Facebook App ID and Secret, which you can read more about here: https://developers.facebook.com) + +## Comments and Replies + +Talk supports a standard comment hierarchy. There are top-level (or parent) comments, and then replies to that comment (or children comments). + +**Permalinks** + +All levels of comments and replies are able to be linked to via permalink. Permalinks are structured using a `commentId` query param: + +https://domain.com/article-asset-slug/?commentId=0879edd7-1c4f-4918-abd2-a770db446b75 + +**Threading** + +Talk supports by default 3 levels of threading, meaning each top-level comment has a depth of 3 replies; replies beyond that are not nested below the 3rd level. You can adjust this using the `TALK_THREADING_LEVEL` configuration variable. We don’t recommend deep threading because it can cause issues with styling, especially on mobile. + +You can style threaded comments using these CSS classes: + + ``` + talk-stream-comment-wrapper-level-${depth} + talk-stream-comment + talk-stream-comment-level-${depth} + talk-stream-highlighted-comment + talk-stream-pending-comment +``` + +**Automatic Updates** + +Talk supports real-time loading and updating of comments, via subscriptions (specifically GraphQL Subscriptions); this enables us to not have to refresh to see new comments on a given comment stream. + +Talk enables this via “Load More” buttons for both top-level comments (this button appears at the top of the stream), and within conversation threads (this button appears in situ for replies). + +We’ve decided to go this route in order to make the viewing experience as smooth as possible, so that the feed of comments doesn’t change as you’re reading just because new comments are coming in. This could be especially disruptive on breaking news and/or controversial stories with very active discussions. + +**Comment Character Limits** + +You can enable Talk to limit the character length for comments, for example, some newsrooms we’ve worked with prefer a limit between 2000 and 5000 characters. Commenters will be alerted that they have gone over that number and won’t be able to submit their comment until they’ve edited it. This can be a useful tool to ensure commenters are concise with their comments. + +## Comment Reactions + +Talk comes with a `respect` button out of the box. Why a “respect” button, you ask? [Read more here](https://mediaengagement.org/research/engagement-buttons/). + +We also have 2 more plugins, `like` and `love`, that you can turn on and experiment with on your own Talk install. + +And our plugin architecture makes it easy to create your own custom reaction buttons too. + +## Reporting Comments + +Readers can report comments if they feel they’re unsuitable. They can choose one of the following reasons: + +* This comment is offensive +* This looks like an ad/marketing +* I don’t agree with this comment +* Other + +They can also include more information and this shows for moderators in the Flag Detail area on the comments in the moderation queues. + +Comments that are reported go to the Reported queue, with the exception of “I don’t agree with this comment”. This option is a useful way to let other readers vent their frustration, but since just disagreeing with something doesn’t mean it’s not suitable, we leave it be. + + +## Reporting Usernames + +Usernames can also be reported by readers, if the username is inappropriate or offensive. They can choose one of the following reasons: + +* This username is offensive +* I don't like this username +* This user is impersonating +* This looks like an ad/marketing + +Reported usernames go to the Reported Usernames queue which is located in the Community tab. If a username is rejected by a moderator, the commenter is prompted to change their username and they are suspended from commenting, replying or reacting to comments until they do so. They receive an email, and also a message at the top of their comment streams that let’s them know they’re suspended. + +If the commenter changes their username, it goes back to the Reported Usernames queue for approval. If the updated username is accepted by a moderator, the commenter is no longer suspended and continue interacting with the community. If the username is rejected, the commenter remains suspended until they change their username to something appropriate. + +Approved usernames that are reported do not show up in the Reported Usernames queues any longer, since they have been specifically OK’ed by a moderator. + +## Ignoring Users + +Commenters can ignore other commenters and essentially mute them entirely from the comment platform. Commenters can manage their ignored users list in their My Profile tab. + +## Featured Comments + +Moderators can feature comments that they want to highlight and recommend to their community. Featured comments show up on a separate tab, that is the default for the comment stream. Featured comments within the stream show a Featured badge. + +## Sorting the Stream + +Readers can sort the stream in 4 ways based on their viewing preferencet: + +* Oldest first +* Newest first +* Most respect first (or most liked, most loved, etc., depending on what reactions you use) +* Most replied first + +We also make it easy to add more sorts via custom plugins. + +## Badges + +Badges differentiate users and comments on the stream. By default, Talk has two badges. + +The Staff user badge that shows when a commenter has an Admin, Moderator, or Staff role. + +The Featured comment badge shows when a comment has been featured. + +Another optional badge is the Subscriber badge (which is available as a [Recipe](/plugin-recipes/#recipe-subscriber). + +Badges are another easy part of Talk to customize by creating a new `tag`, then setting some rules for when it should show, and how the badge should be styled. + +## My Profile + +The My Profile tab is where commenters can go to see their comment history, as well as reactions and replies to their comments. They can also see their email address associated with Talk, and manage their Ignored Users list here. + +## Notifications & Error Messaging + +Talk leverages notification and messages on the stream to alert users to important information about their comment or their account. + +**Pre-moderation of comments** + +If a stream is set to Pre-mod, or a commenter’s Trust karma score has fallen to negative, or if for any other reason their comment is being pre-moderated, they will get a notification letting them know this when they post a comment. + +**Suspension because of Username** + +When a commenter has been suspended because their username is inappropriate, they will see a message at the top of their streams stating this. + +**Timed Suspension** + +When a commenter has been suspended for a block of time (aka a “time-out”), they will see a message at the top of their streams stating this. + +**Ban** + +When a commenter has been banned, they will see a message at the top of their streams staging this. From aa0c41c342e66ecd254d4024ed4b9997c9c5cc29 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Sat, 14 Oct 2017 18:25:41 +0100 Subject: [PATCH 04/15] Add section Moderator Features --- .../03-03-product-guide-moderator-features.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/docs/_docs/03-03-product-guide-moderator-features.md b/docs/_docs/03-03-product-guide-moderator-features.md index 355c40a1c..142fb8652 100644 --- a/docs/_docs/03-03-product-guide-moderator-features.md +++ b/docs/_docs/03-03-product-guide-moderator-features.md @@ -2,3 +2,128 @@ title: Moderator Features permalink: /moderator-features/ --- + +## The Talk Admin + +The Admin is your moderators will moderate your comments, and your Admins will configure and manage the different parts of Talk. + +### Dashboard + +The Dashboard provides real-time information to moderators so they know at a glance where they should direct their attention. It shows what articles are receiving the most reports and where the most active conversations are happening. + +### Moderate + +This is the tab where Moderators will spend the majority of their time. They can choose (via the dropdown) which story they would like to moderate, or moderate site-wide. + +#### Default Mod Queues + +**New** + +The New queue contains all comments that have not been moderated yet. + +**Reported** + +The Reported queue contains all comments that need moderator attention. + +**Approved** + +The Approved queue contains all approved comments. + +**Rejected** + +The Rejected queue contains all comments that have been rejected, either manually by moderators or automatically, e.g. they have used a banned word. + +**All** + +The All queue contains all comments that have been submitted either article or site-wide. + +#### Moderation Badges + +**Pre-mod** + +The Pre-mod badge signifies comments that are being pre-modded. + +**User** + +The User badge signifies comments that have been reported by another user. + +**History** + +The History badge signifies comments that have been flagged because of a user’s history. + +**Toxic** + +The Toxic badge signifies comments that are above the set Toxicity Probability Threshold. Note you must have `talk-plugin-toxic-comments` enabled. [Read more about Toxic Comments here](LINK). + +**Suspect** + +The Suspect badge signifies comments that contain a Suspect Word. [Read more about Suspect Words here](LINK). + +**Contains Link** + +The Contains Link badge signifies a comment that contains a link, which can sometimes mean it is a spam or ad comment. + +**Flag Details View** + +At the bottom of each comment in the moderation queues, you can see more information about a comment’s flags by clicking on More Detail. + +#### Moderator Actions + +**Accept** + +Accepting a comment ensures that the comment is displayed on the stream. + +**Reject** + +Rejecting a comment removes the comment from the stream. + +**Feature** + +Featuring a comment adds that comment to the Featured Comments tab on the stream. + +**Suspend User** + +Suspending a user allows a moderator to give a commenter a “time-out”; during that time they won’t be allowed to post comments or react to comments. + +**Ban User** + +Banning a user allows a moderator to permanently disallow a commenter to interact with their community. The commenter’s previous comments will remain on the site. This action can only be un-done manually by a moderator. + +#### Viewing a User’s Comment History + +In order to get an idea of what sort of a commenter someone is, moderators can click on the commenter’s username in any moderation queue and see details about their history. + +**Username, Email and Member Since Date** + +This shows the basic details about a commenter. + +**Total Comments** + +This shows the number of comments that a commenter has made that currently display on the site. + +**Reject Rate** + +This shows the % of comments a commenter has had rejected by moderators, or automatically. + +**Reports** + +This shows if a commenter is a reliable flagger, an unreliable flagger, or a neutral flagger. [Read more about reliable and unreliable flaggers here](LINK). + +**Moderating from this View** + +Talk also allows you to moderate a commenter’s recent comments from this view. + +#### Keyboard Shortcuts + +Talk also supports a number of keyboard shortcuts that moderators can leverage to moderate quickly: + +| Shortcut | Action | +| -------- | ------------------------------- | +| `j` | Go to the next comment | +| `k` | Go to the previous comment | +| `ctrl+f` | Open search | +| `t` | Switch queues | +| `s` | Toggle single comment edit view | +| `?` | Open this menu | +| `d` | Approve | +| `f` | Reject | From 759338dc02fa18150f0e271780e762edb5c0ffbc Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Sat, 14 Oct 2017 18:36:17 +0100 Subject: [PATCH 05/15] Added more Moderator Features --- .../03-03-product-guide-moderator-features.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/_docs/03-03-product-guide-moderator-features.md b/docs/_docs/03-03-product-guide-moderator-features.md index 142fb8652..98fa5fc4c 100644 --- a/docs/_docs/03-03-product-guide-moderator-features.md +++ b/docs/_docs/03-03-product-guide-moderator-features.md @@ -127,3 +127,26 @@ Talk also supports a number of keyboard shortcuts that moderators can leverage t | `?` | Open this menu | | `d` | Approve | | `f` | Reject | + +### Stories + +In the Stories tab moderators can view all the stories that have Talk comments embedded on them, as well as be able to Open or Close comment streams on stories. + +### Community + +The Community tab houses everything having to do with your team and your commenters. + +#### Moderating Usernames + +Any usernames that have been reported will show in the Reported Usernames sub-tab. Moderators can approve usernames if they’re suitable, or reject a username. If a username is rejected, the commenter will be notified that they need to change their username; until they do, they will be suspended from Talk. The updated username then again appears in this queue for a decision by moderators. + +#### Managing People & Roles + +All your team and commenters show in the People sub-tab. From here, you can manage your team members’ roles (Admins, Moderators, Staff), as well as search for commenters and take action on them (e.g. Ban/Un-ban, Suspend, etc.). +### Configure + +See [Configuring Talk](LINK). + +## Moderating via the Comment Stream + +Moderators can also choose to moderate comments in situ. If you are logged in as a Moderator or Admin, you will see a caret dropdown on each comment that allows you to Approve, Reject, or Feature comments, or Ban a User directly from the comment stream. From c8f432268be247287f23079d938b512697cfcb77 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Sat, 14 Oct 2017 18:41:50 +0100 Subject: [PATCH 06/15] Add Nav for Configuring Talk section --- docs/_data/nav.yaml | 2 ++ docs/_docs/03-06-product-guide-configuring-talk.md | 4 ++++ 2 files changed, 6 insertions(+) create mode 100644 docs/_docs/03-06-product-guide-configuring-talk.md diff --git a/docs/_data/nav.yaml b/docs/_data/nav.yaml index 9a205e8fe..41d0f7bda 100644 --- a/docs/_data/nav.yaml +++ b/docs/_data/nav.yaml @@ -25,6 +25,8 @@ items: url: /trust/ - title: Toxic Comments url: /toxic-comments/ + - title: Configuring Talk + url: /configuring-talk/ - title: Plugins children: - title: Plugins Overview diff --git a/docs/_docs/03-06-product-guide-configuring-talk.md b/docs/_docs/03-06-product-guide-configuring-talk.md new file mode 100644 index 000000000..c4089d16c --- /dev/null +++ b/docs/_docs/03-06-product-guide-configuring-talk.md @@ -0,0 +1,4 @@ +--- +title: Configuring Talk +permalink: /configuring-talk/ +--- From a167b6ce2c88e8234f453afb887493588127ba41 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Mon, 16 Oct 2017 18:20:25 +0100 Subject: [PATCH 07/15] Add Stream Configuration docs --- .../03-06-product-guide-configuring-talk.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/_docs/03-06-product-guide-configuring-talk.md b/docs/_docs/03-06-product-guide-configuring-talk.md index c4089d16c..2d50157aa 100644 --- a/docs/_docs/03-06-product-guide-configuring-talk.md +++ b/docs/_docs/03-06-product-guide-configuring-talk.md @@ -2,3 +2,27 @@ title: Configuring Talk permalink: /configuring-talk/ --- + +## Configuring an Individual Stream + +There are two ways Admins can configure Talk - the first is via the Configure tab on the comment stream. + +### Enable Pre-moderation + +Allows toggling pre-moderation for the current comment stream. + +### Pre-moderation Comments Containing Links + +Allows toggling of pre-moderating comments that have links. + +### Ask Readers a Question & Question Icons + +Admins can choose to Ask Readers a Question in order to help guide the discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/). + +Admins can also use different icons to display different messaging other than a question on a particular stream, like an announcement or general information about the story. + +### Closing a Stream + +Admins can close a comment stream which disallows new comments. Previous comments will remain displayed on the stream for readers to view. + +## Global Configuration From 988cb870bb87a0e5dffb63c0601fe9dc188e6189 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Tue, 17 Oct 2017 10:13:40 +0100 Subject: [PATCH 08/15] Global Configuration docs --- .../03-06-product-guide-configuring-talk.md | 64 ++++++++++++++++++- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/docs/_docs/03-06-product-guide-configuring-talk.md b/docs/_docs/03-06-product-guide-configuring-talk.md index 2d50157aa..845c6ec19 100644 --- a/docs/_docs/03-06-product-guide-configuring-talk.md +++ b/docs/_docs/03-06-product-guide-configuring-talk.md @@ -19,10 +19,70 @@ Allows toggling of pre-moderating comments that have links. Admins can choose to Ask Readers a Question in order to help guide the discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/). -Admins can also use different icons to display different messaging other than a question on a particular stream, like an announcement or general information about the story. +There are a selection of icons to display different messaging other than a question on a particular stream, like an announcement, or general information about the story. ### Closing a Stream -Admins can close a comment stream which disallows new comments. Previous comments will remain displayed on the stream for readers to view. +Closing a stream will prevent new comments. Previous comments will remain displayed on the stream for readers to view. + ## Global Configuration + +Global configuration settings are available via Admin > Configure. These settings are site-wide and will affect all of your comment streams. + +### Stream Settings + +#### Limit Comment Length + +A maximum comment length across the site. + +#### Comment Stream Description + +Description text that will appear above every comment stream site-wide. We recommend linking to your Code of Conduct or Community Guidelines. [Read tips on how to write a Code of Conduct here](https://guides.coralproject.net/create-a-code-of-conduct/). + +#### Closed Stream Message + +A message that will display when streams are closed. + +#### Edit Comment Timeframe + +The timeframe in seconds in which commenters have to edit their comment. + +#### Close Comments After + +Default time after which all comment streams will close. + +### Moderation Settings + +#### Require Email Verification + +Require new users to verify their email address prior to commenting. + +#### Enable Pre-moderation + +Turn on pre-moderation across the site, meaning all comments will need to be moderated before they will be displayed. + +#### Pre-moderate Comments Containing Links + +Turn on pre-moderation for comments with links across the site, meaning all comments with links will need to be moderated before they will be displayed. + +#### Banned Words List + +A list of words that will trigger a comment to be automatically Rejected. + +#### Suspect Words List + +A list of words that will trigger a comment to be automatically Reported. Comments with suspect words will display until a moderator takes action on them. + +### Technical Settings + +#### Permitted Domains +A list of domains where your Talk instance is allowed to be embedded. Typical use is `localhost`, `staging.yourdomain.com`, `yourdomain.com`, etc. + +#### Embed Script + +This is the unique Talk script that is to be used to embed Talk on your website. + +#### Custom CSS URL + +The link to your custom stylesheet for Talk. This will override any default styles, so you can make Talk your own! From 3a8ed3033a0a11411addd30e9a26c2a623279e41 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Tue, 17 Oct 2017 10:28:56 +0100 Subject: [PATCH 09/15] Fix styling --- .../03-02-product-guide-commenter-features.md | 16 +++++++-------- docs/_docs/03-04-product-guide-trust.md | 4 ++-- .../03-05-product-guide-toxic-comments.md | 6 +++--- docs/_sass/talk.scss | 20 +++++++++++++++---- 4 files changed, 29 insertions(+), 17 deletions(-) diff --git a/docs/_docs/03-02-product-guide-commenter-features.md b/docs/_docs/03-02-product-guide-commenter-features.md index 81ec5128d..cffd16316 100644 --- a/docs/_docs/03-02-product-guide-commenter-features.md +++ b/docs/_docs/03-02-product-guide-commenter-features.md @@ -17,13 +17,13 @@ We also provide a Facebook auth plugin that supports logging in with Facebook (y Talk supports a standard comment hierarchy. There are top-level (or parent) comments, and then replies to that comment (or children comments). -**Permalinks** +### Permalinks All levels of comments and replies are able to be linked to via permalink. Permalinks are structured using a `commentId` query param: https://domain.com/article-asset-slug/?commentId=0879edd7-1c4f-4918-abd2-a770db446b75 -**Threading** +### Threading Talk supports by default 3 levels of threading, meaning each top-level comment has a depth of 3 replies; replies beyond that are not nested below the 3rd level. You can adjust this using the `TALK_THREADING_LEVEL` configuration variable. We don’t recommend deep threading because it can cause issues with styling, especially on mobile. @@ -37,7 +37,7 @@ You can style threaded comments using these CSS classes: talk-stream-pending-comment ``` -**Automatic Updates** +### Automatic Updates Talk supports real-time loading and updating of comments, via subscriptions (specifically GraphQL Subscriptions); this enables us to not have to refresh to see new comments on a given comment stream. @@ -45,7 +45,7 @@ Talk enables this via “Load More” buttons for both top-level comments (this We’ve decided to go this route in order to make the viewing experience as smooth as possible, so that the feed of comments doesn’t change as you’re reading just because new comments are coming in. This could be especially disruptive on breaking news and/or controversial stories with very active discussions. -**Comment Character Limits** +### Comment Character Limits You can enable Talk to limit the character length for comments, for example, some newsrooms we’ve worked with prefer a limit between 2000 and 5000 characters. Commenters will be alerted that they have gone over that number and won’t be able to submit their comment until they’ve edited it. This can be a useful tool to ensure commenters are concise with their comments. @@ -125,18 +125,18 @@ The My Profile tab is where commenters can go to see their comment history, as w Talk leverages notification and messages on the stream to alert users to important information about their comment or their account. -**Pre-moderation of comments** +### Pre-moderation of comments If a stream is set to Pre-mod, or a commenter’s Trust karma score has fallen to negative, or if for any other reason their comment is being pre-moderated, they will get a notification letting them know this when they post a comment. -**Suspension because of Username** +### Suspension because of Username When a commenter has been suspended because their username is inappropriate, they will see a message at the top of their streams stating this. -**Timed Suspension** +### Timed Suspension When a commenter has been suspended for a block of time (aka a “time-out”), they will see a message at the top of their streams stating this. -**Ban** +### Ban When a commenter has been banned, they will see a message at the top of their streams staging this. diff --git a/docs/_docs/03-04-product-guide-trust.md b/docs/_docs/03-04-product-guide-trust.md index 42587d203..396ecd07d 100644 --- a/docs/_docs/03-04-product-guide-trust.md +++ b/docs/_docs/03-04-product-guide-trust.md @@ -6,7 +6,7 @@ permalink: /trust/ Trust is a set of components within Talk that incorporate automated moderation features based on a user's previous behavior. -### User Karma Score +## User Karma Score Using Trust’s calculations, Talk will automatically pre-moderate comments of users who have a negative karma score. All users start out with a `0` neutral @@ -32,7 +32,7 @@ You can configure your own Trust thresholds by using [TRUST_THRESHOLD]({{"/advan configuration. -### Reliable and Unreliable Flaggers +## Reliable and Unreliable Flaggers Trust also calculates how reliable users are in terms of the comments they report. This information is displayed to moderators in the User History drawer, diff --git a/docs/_docs/03-05-product-guide-toxic-comments.md b/docs/_docs/03-05-product-guide-toxic-comments.md index 56677a421..ac680916d 100644 --- a/docs/_docs/03-05-product-guide-toxic-comments.md +++ b/docs/_docs/03-05-product-guide-toxic-comments.md @@ -21,7 +21,7 @@ Talk (0.8 or 80% is the default), which works like this: Read more about Coral’s take on toxicity [on our blog](https://blog.coralproject.net/toxic-avenging/){:target="_blank"}. -### What is the Perspective API? +## What is the Perspective API? The likely toxicity of a comment is evaluated using scores generated from [Perspective API](http://perspectiveapi.com/){:target="_blank"}. This is part of @@ -48,12 +48,12 @@ We’ve talked with their team on several occasions, and have been impressed by their dedication and commitment to this issue. These are smart people who are trying to improve a broken part of the internet. -### How do I add the Toxic Comments plugin? +## How do I add the Toxic Comments plugin? To enable this behavior, visit the [talk-plugin-toxic-comments]({{ "/additional-plugins/#talk-plugin-toxic-comments" | relative_url }}) plugin documentation. -### Request an API Key +## Request an API Key You can read more about Google's Perspective API and/or request an API key here: [http://perspectiveapi.com/](http://perspectiveapi.com/). diff --git a/docs/_sass/talk.scss b/docs/_sass/talk.scss index 69e039951..e967d10e4 100644 --- a/docs/_sass/talk.scss +++ b/docs/_sass/talk.scss @@ -16,11 +16,25 @@ body { } h1 { - font-size: 1.7em; + font-size: 2rem; } -h2, h3, h4 { +h2 { margin: 1.6em 0 0.8em; + font-size: 1.75rem; + font-weight: 600; +} + +h3 { + margin: 1.6em 0 0.8em; + font-size: 1.5rem; + font-weight: 500; +} + +h4 { + margin: 1.6em 0 0.8em; + font-size: 1.2rem; + font-weight: 500; } .btn-coral { @@ -41,7 +55,6 @@ h2, h3, h4 { } article.configuration { - h2, .toc { @extend .param; } @@ -408,4 +421,3 @@ a.brand { } } } - From a586756ac9ad82289d83377e33bf8ac644988dea Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Tue, 17 Oct 2017 12:27:33 +0100 Subject: [PATCH 10/15] Add FAQ and Tutorial sections --- docs/_data/nav.yaml | 8 ++++++++ docs/_docs/05-01-faq.md | 16 ++++++++++++++++ docs/_docs/06-01-developer-tutorials.md | 18 ++++++++++++++++++ 3 files changed, 42 insertions(+) create mode 100644 docs/_docs/05-01-faq.md create mode 100644 docs/_docs/06-01-developer-tutorials.md diff --git a/docs/_data/nav.yaml b/docs/_data/nav.yaml index 41d0f7bda..753607355 100644 --- a/docs/_data/nav.yaml +++ b/docs/_data/nav.yaml @@ -37,3 +37,11 @@ items: url: /additional-plugins/ - title: Plugin Recipes url: /plugin-recipes/ + - title: FAQ + children: + - title: FAQ + url: /faq/ + - title: Developer Tutorials + children: + - title: Developer Tutorials + url: /developer-tutorials/ diff --git a/docs/_docs/05-01-faq.md b/docs/_docs/05-01-faq.md new file mode 100644 index 000000000..c084bc903 --- /dev/null +++ b/docs/_docs/05-01-faq.md @@ -0,0 +1,16 @@ +--- +title: FAQ +permalink: /faq/ +--- + +## How can I get help integrating Talk into my newsroom? + +We're here to help with newsrooms of all sizes. Email our Integration Engineer (jeff@mozillafoundation.org) to set up a meeting. + +## How do I request a feature or submit a bug? + +The best way is to [submit a Github issue](https://github.com/coralproject/talk/issues). Make sure you give plenty of details, our Core Team can usually respond within a few hours on weekdays. + +## How can our dev team contribute to Talk? + +We are lucky to work with newsroom dev teams and individual contributors who span the world, and come from newsrooms of all sizes. You can read our [Contribution Guide](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md) to get started, but feel free to reach out to us via Github, or get in touch directly with Jeff via jeff@mozillafoundation.org. diff --git a/docs/_docs/06-01-developer-tutorials.md b/docs/_docs/06-01-developer-tutorials.md new file mode 100644 index 000000000..e03b88e0c --- /dev/null +++ b/docs/_docs/06-01-developer-tutorials.md @@ -0,0 +1,18 @@ +--- +title: Developer Tutorials +permalink: /developer-tutorials/ +--- + +Coming soon! + +**How can I connect Talk to my own app/newsroom/blog’s auth?** + +**How can I display a story’s comment count externally?** + +**How can I add a moderation queue that filters by a tag?** + +**How can I manage Assets with Talk?** + +**How can I style Talk?** + +**How do I submit a PR to Talk?** From 39a209231038956b5d7585649b050b6e006e9023 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Tue, 17 Oct 2017 12:32:56 +0100 Subject: [PATCH 11/15] Add faq --- docs/_docs/06-01-developer-tutorials.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_docs/06-01-developer-tutorials.md b/docs/_docs/06-01-developer-tutorials.md index e03b88e0c..de0065132 100644 --- a/docs/_docs/06-01-developer-tutorials.md +++ b/docs/_docs/06-01-developer-tutorials.md @@ -13,6 +13,8 @@ Coming soon! **How can I manage Assets with Talk?** +**How can I add a new translation for Talk?** + **How can I style Talk?** **How do I submit a PR to Talk?** From 8ce9f2d4bbbcf44ea361526544dc38eac91baca3 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Fri, 20 Oct 2017 11:28:03 +0100 Subject: [PATCH 12/15] Clean up docs, fix links, remove Tutorials section for now --- docs/_data/nav.yaml | 4 ---- .../03-02-product-guide-commenter-features.md | 6 +++--- .../03-03-product-guide-moderator-features.md | 8 ++++---- .../03-06-product-guide-configuring-talk.md | 4 ++-- docs/_docs/06-01-developer-tutorials.md | 20 ------------------- 5 files changed, 9 insertions(+), 33 deletions(-) delete mode 100644 docs/_docs/06-01-developer-tutorials.md diff --git a/docs/_data/nav.yaml b/docs/_data/nav.yaml index 753607355..9138d6603 100644 --- a/docs/_data/nav.yaml +++ b/docs/_data/nav.yaml @@ -41,7 +41,3 @@ items: children: - title: FAQ url: /faq/ - - title: Developer Tutorials - children: - - title: Developer Tutorials - url: /developer-tutorials/ diff --git a/docs/_docs/03-02-product-guide-commenter-features.md b/docs/_docs/03-02-product-guide-commenter-features.md index cffd16316..76cd81cd1 100644 --- a/docs/_docs/03-02-product-guide-commenter-features.md +++ b/docs/_docs/03-02-product-guide-commenter-features.md @@ -25,7 +25,7 @@ https://domain.com/article-asset-slug/?commentId=0879edd7-1c4f-4918-abd2-a770db4 ### Threading -Talk supports by default 3 levels of threading, meaning each top-level comment has a depth of 3 replies; replies beyond that are not nested below the 3rd level. You can adjust this using the `TALK_THREADING_LEVEL` configuration variable. We don’t recommend deep threading because it can cause issues with styling, especially on mobile. +Talk supports by default 3 levels of threading, meaning each top-level comment has a depth of 3 replies; replies beyond that are not nested below the 3rd level. You can adjust this using the [`TALK_THREADING_LEVEL`]({{ "/advanced-configuration/#talk_threading_level" | relative_url }})configuration variable. We don’t recommend deep threading because it can cause issues with styling, especially on mobile. You can style threaded comments using these CSS classes: @@ -51,7 +51,7 @@ You can enable Talk to limit the character length for comments, for example, som ## Comment Reactions -Talk comes with a `respect` button out of the box. Why a “respect” button, you ask? [Read more here](https://mediaengagement.org/research/engagement-buttons/). +Talk comes with a `respect` button out of the box. Why a “respect” button, you ask? [Read more here](https://mediaengagement.org/research/engagement-buttons/){:target="_blank"}. We also have 2 more plugins, `like` and `love`, that you can turn on and experiment with on your own Talk install. @@ -113,7 +113,7 @@ The Staff user badge that shows when a commenter has an Admin, Moderator, or Sta The Featured comment badge shows when a comment has been featured. -Another optional badge is the Subscriber badge (which is available as a [Recipe](/plugin-recipes/#recipe-subscriber). +Another optional badge is the Subscriber badge (which is available as a [Recipe]({{ "/plugin-recipes/#recipe-subscriber" | relative_url}}). Badges are another easy part of Talk to customize by creating a new `tag`, then setting some rules for when it should show, and how the badge should be styled. diff --git a/docs/_docs/03-03-product-guide-moderator-features.md b/docs/_docs/03-03-product-guide-moderator-features.md index 98fa5fc4c..73252de7a 100644 --- a/docs/_docs/03-03-product-guide-moderator-features.md +++ b/docs/_docs/03-03-product-guide-moderator-features.md @@ -53,11 +53,11 @@ The History badge signifies comments that have been flagged because of a user’ **Toxic** -The Toxic badge signifies comments that are above the set Toxicity Probability Threshold. Note you must have `talk-plugin-toxic-comments` enabled. [Read more about Toxic Comments here](LINK). +The Toxic badge signifies comments that are above the set Toxicity Probability Threshold. Note you must have `talk-plugin-toxic-comments` enabled. [Read more about Toxic Comments here]({{ "/toxic-comments/" | relative_url}}). **Suspect** -The Suspect badge signifies comments that contain a Suspect Word. [Read more about Suspect Words here](LINK). +The Suspect badge signifies comments that contain a Suspect Word. **Contains Link** @@ -107,7 +107,7 @@ This shows the % of comments a commenter has had rejected by moderators, or auto **Reports** -This shows if a commenter is a reliable flagger, an unreliable flagger, or a neutral flagger. [Read more about reliable and unreliable flaggers here](LINK). +This shows if a commenter is a reliable flagger, an unreliable flagger, or a neutral flagger. [Read more about reliable and unreliable flaggers here]({{ "/trust/#reliable-and-unreliable-flaggers" | relative_url }}). **Moderating from this View** @@ -145,7 +145,7 @@ Any usernames that have been reported will show in the Reported Usernames sub-ta All your team and commenters show in the People sub-tab. From here, you can manage your team members’ roles (Admins, Moderators, Staff), as well as search for commenters and take action on them (e.g. Ban/Un-ban, Suspend, etc.). ### Configure -See [Configuring Talk](LINK). +See [Configuring Talk]({{ "/configuring-talk/" | relative_url }}). ## Moderating via the Comment Stream diff --git a/docs/_docs/03-06-product-guide-configuring-talk.md b/docs/_docs/03-06-product-guide-configuring-talk.md index 845c6ec19..3225b31bb 100644 --- a/docs/_docs/03-06-product-guide-configuring-talk.md +++ b/docs/_docs/03-06-product-guide-configuring-talk.md @@ -17,7 +17,7 @@ Allows toggling of pre-moderating comments that have links. ### Ask Readers a Question & Question Icons -Admins can choose to Ask Readers a Question in order to help guide the discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/). +Admins can choose to Ask Readers a Question in order to help guide the discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/){:target="_blank"}. There are a selection of icons to display different messaging other than a question on a particular stream, like an announcement, or general information about the story. @@ -38,7 +38,7 @@ A maximum comment length across the site. #### Comment Stream Description -Description text that will appear above every comment stream site-wide. We recommend linking to your Code of Conduct or Community Guidelines. [Read tips on how to write a Code of Conduct here](https://guides.coralproject.net/create-a-code-of-conduct/). +Description text that will appear above every comment stream site-wide. We recommend linking to your Code of Conduct or Community Guidelines. [Read tips on how to write a Code of Conduct here](https://guides.coralproject.net/create-a-code-of-conduct/){:target="_blank"}. #### Closed Stream Message diff --git a/docs/_docs/06-01-developer-tutorials.md b/docs/_docs/06-01-developer-tutorials.md deleted file mode 100644 index de0065132..000000000 --- a/docs/_docs/06-01-developer-tutorials.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Developer Tutorials -permalink: /developer-tutorials/ ---- - -Coming soon! - -**How can I connect Talk to my own app/newsroom/blog’s auth?** - -**How can I display a story’s comment count externally?** - -**How can I add a moderation queue that filters by a tag?** - -**How can I manage Assets with Talk?** - -**How can I add a new translation for Talk?** - -**How can I style Talk?** - -**How do I submit a PR to Talk?** From e0713a5ec40444de1f96db499bc85b4ad5efd2fa Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Fri, 20 Oct 2017 17:56:24 +0100 Subject: [PATCH 13/15] Update auth section --- docs/_docs/03-02-product-guide-commenter-features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_docs/03-02-product-guide-commenter-features.md b/docs/_docs/03-02-product-guide-commenter-features.md index 76cd81cd1..07c64bd0f 100644 --- a/docs/_docs/03-02-product-guide-commenter-features.md +++ b/docs/_docs/03-02-product-guide-commenter-features.md @@ -7,9 +7,9 @@ permalink: /commenter-features/ There are 2 ways that newsrooms can support signup/login functionality with Talk: -Use Talk’s auth plugin out of the box (supports account registration with username and password, as well as features like forgot password) +*Use Talk’s auth plugin out of the box (supports account registration with username and password, as well as features like forgot password) -Create their own auth plugin (you can use ours as a template) to integrate with your own auth systems +*Create their own auth plugin to integrate with your own auth systems We also provide a Facebook auth plugin that supports logging in with Facebook (you must provide your own Facebook App ID and Secret, which you can read more about here: https://developers.facebook.com) From c1b954965f02e2f75296558063ed5e848b9f8f35 Mon Sep 17 00:00:00 2001 From: Wyatt Johnson Date: Fri, 20 Oct 2017 11:40:55 -0600 Subject: [PATCH 14/15] Fixed incorrect plugin naming --- docs/_docs/04-02-default-plugins.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/_docs/04-02-default-plugins.md b/docs/_docs/04-02-default-plugins.md index aff17ebcc..5c987172d 100644 --- a/docs/_docs/04-02-default-plugins.md +++ b/docs/_docs/04-02-default-plugins.md @@ -98,17 +98,17 @@ Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param} Provides a sort for the newest comments first. -## talk-plugin-most-respected +## talk-plugin-sort-most-respected -Source: [plugins/talk-plugin-most-respected](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-most-respected){:target="_blank"} +Source: [plugins/talk-plugin-sort-most-respected](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-respected){:target="_blank"} Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param}, [talk-plugin-respect](#talk-plugin-respect){:.param} Provides a sort for the comments with the most `respect` reactions first. -## talk-plugin-most-replied +## talk-plugin-sort-most-replied -Source: [plugins/talk-plugin-most-replied](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-most-replied){:target="_blank"} +Source: [plugins/talk-plugin-sort-most-replied](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-replied){:target="_blank"} Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param} From a9cb206415f5dbfdf07e6f031a16fdd98ffcfae8 Mon Sep 17 00:00:00 2001 From: Wyatt Johnson Date: Fri, 20 Oct 2017 13:14:00 -0600 Subject: [PATCH 15/15] formatting --- .../03-02-product-guide-commenter-features.md | 136 +++++++++++++----- .../03-03-product-guide-moderator-features.md | 86 +++++++---- .../03-06-product-guide-configuring-talk.md | 35 +++-- docs/_docs/05-01-faq.md | 3 +- 4 files changed, 184 insertions(+), 76 deletions(-) diff --git a/docs/_docs/03-02-product-guide-commenter-features.md b/docs/_docs/03-02-product-guide-commenter-features.md index 76cd81cd1..d36fc2b27 100644 --- a/docs/_docs/03-02-product-guide-commenter-features.md +++ b/docs/_docs/03-02-product-guide-commenter-features.md @@ -9,134 +9,192 @@ There are 2 ways that newsrooms can support signup/login functionality with Talk Use Talk’s auth plugin out of the box (supports account registration with username and password, as well as features like forgot password) -Create their own auth plugin (you can use ours as a template) to integrate with your own auth systems +Create their own auth plugin to integrate with your own auth systems -We also provide a Facebook auth plugin that supports logging in with Facebook (you must provide your own Facebook App ID and Secret, which you can read more about here: https://developers.facebook.com) +We also provide a Facebook auth plugin that supports logging in with Facebook (you must provide your own Facebook App ID and Secret, which you can read more about here: [https://developers.facebook.com](https://developers.facebook.com){:target="_blank"}) ## Comments and Replies -Talk supports a standard comment hierarchy. There are top-level (or parent) comments, and then replies to that comment (or children comments). +Talk supports a standard comment hierarchy. There are top-level (or parent) comments, and then replies to that comment (or children comments). ### Permalinks All levels of comments and replies are able to be linked to via permalink. Permalinks are structured using a `commentId` query param: -https://domain.com/article-asset-slug/?commentId=0879edd7-1c4f-4918-abd2-a770db446b75 +```text +https://?commentId= +``` +{:.no-copy} ### Threading -Talk supports by default 3 levels of threading, meaning each top-level comment has a depth of 3 replies; replies beyond that are not nested below the 3rd level. You can adjust this using the [`TALK_THREADING_LEVEL`]({{ "/advanced-configuration/#talk_threading_level" | relative_url }})configuration variable. We don’t recommend deep threading because it can cause issues with styling, especially on mobile. +Talk supports by default 3 levels of threading, meaning each top-level comment +has a depth of 3 replies; replies beyond that are not nested below the 3rd +level. You can adjust this using the +[TALK_THREADING_LEVEL]({{ "/advanced-configuration/#talk_threading_level" | relative_url }}){:.param} +configuration variable. We don’t recommend deep threading because it can cause +issues with styling, especially on mobile. You can style threaded comments using these CSS classes: - ``` - talk-stream-comment-wrapper-level-${depth} - talk-stream-comment - talk-stream-comment-level-${depth} - talk-stream-highlighted-comment - talk-stream-pending-comment ``` +talk-stream-comment-wrapper-level-${depth} +talk-stream-comment +talk-stream-comment-level-${depth} +talk-stream-highlighted-comment +talk-stream-pending-comment +``` +{:.no-copy} ### Automatic Updates -Talk supports real-time loading and updating of comments, via subscriptions (specifically GraphQL Subscriptions); this enables us to not have to refresh to see new comments on a given comment stream. +Talk supports real-time loading and updating of comments, via subscriptions +(specifically GraphQL Subscriptions); this enables us to not have to refresh to +see new comments on a given comment stream. -Talk enables this via “Load More” buttons for both top-level comments (this button appears at the top of the stream), and within conversation threads (this button appears in situ for replies). +Talk enables this via “Load More” buttons for both top-level comments (this +button appears at the top of the stream), and within conversation threads (this +button appears in situ for replies). -We’ve decided to go this route in order to make the viewing experience as smooth as possible, so that the feed of comments doesn’t change as you’re reading just because new comments are coming in. This could be especially disruptive on breaking news and/or controversial stories with very active discussions. +We’ve decided to go this route in order to make the viewing experience as smooth +as possible, so that the feed of comments doesn’t change as you’re reading just +because new comments are coming in. This could be especially disruptive on +breaking news and/or controversial stories with very active discussions. ### Comment Character Limits -You can enable Talk to limit the character length for comments, for example, some newsrooms we’ve worked with prefer a limit between 2000 and 5000 characters. Commenters will be alerted that they have gone over that number and won’t be able to submit their comment until they’ve edited it. This can be a useful tool to ensure commenters are concise with their comments. +You can enable Talk to limit the character length for comments, for example, +some newsrooms we’ve worked with prefer a limit between 2000 and 5000 +characters. Commenters will be alerted that they have gone over that number and +won’t be able to submit their comment until they’ve edited it. This can be a +useful tool to ensure commenters are concise with their comments. ## Comment Reactions -Talk comes with a `respect` button out of the box. Why a “respect” button, you ask? [Read more here](https://mediaengagement.org/research/engagement-buttons/){:target="_blank"}. +Talk comes with a `respect` button out of the box. Why a “respect” button, you +ask? +[Read more here](https://mediaengagement.org/research/engagement-buttons/){:target="_blank"}. -We also have 2 more plugins, `like` and `love`, that you can turn on and experiment with on your own Talk install. +We also have 2 more plugins, `like` and `love`, that you can turn on and +experiment with on your own Talk install. -And our plugin architecture makes it easy to create your own custom reaction buttons too. +And our plugin architecture makes it easy to create your own custom reaction +buttons too. ## Reporting Comments -Readers can report comments if they feel they’re unsuitable. They can choose one of the following reasons: +Readers can report comments if they feel they’re unsuitable. They can choose one +of the following reasons: * This comment is offensive * This looks like an ad/marketing * I don’t agree with this comment * Other -They can also include more information and this shows for moderators in the Flag Detail area on the comments in the moderation queues. +They can also include more information and this shows for moderators in the Flag +Detail area on the comments in the moderation queues. -Comments that are reported go to the Reported queue, with the exception of “I don’t agree with this comment”. This option is a useful way to let other readers vent their frustration, but since just disagreeing with something doesn’t mean it’s not suitable, we leave it be. +Comments that are reported go to the Reported queue, with the exception of “I +don’t agree with this comment”. This option is a useful way to let other readers +vent their frustration, but since just disagreeing with something doesn’t mean +it’s not suitable, we leave it be. ## Reporting Usernames -Usernames can also be reported by readers, if the username is inappropriate or offensive. They can choose one of the following reasons: +Usernames can also be reported by readers, if the username is inappropriate or +offensive. They can choose one of the following reasons: * This username is offensive * I don't like this username * This user is impersonating * This looks like an ad/marketing -Reported usernames go to the Reported Usernames queue which is located in the Community tab. If a username is rejected by a moderator, the commenter is prompted to change their username and they are suspended from commenting, replying or reacting to comments until they do so. They receive an email, and also a message at the top of their comment streams that let’s them know they’re suspended. +Reported usernames go to the Reported Usernames queue which is located in the +Community tab. If a username is rejected by a moderator, the commenter is +prompted to change their username and they are suspended from commenting, +replying or reacting to comments until they do so. They receive an email, and +also a message at the top of their comment streams that let’s them know they’re +suspended. -If the commenter changes their username, it goes back to the Reported Usernames queue for approval. If the updated username is accepted by a moderator, the commenter is no longer suspended and continue interacting with the community. If the username is rejected, the commenter remains suspended until they change their username to something appropriate. +If the commenter changes their username, it goes back to the Reported Usernames +queue for approval. If the updated username is accepted by a moderator, the +commenter is no longer suspended and continue interacting with the community. If +the username is rejected, the commenter remains suspended until they change +their username to something appropriate. -Approved usernames that are reported do not show up in the Reported Usernames queues any longer, since they have been specifically OK’ed by a moderator. +Approved usernames that are reported do not show up in the Reported Usernames +queues any longer, since they have been specifically OK’ed by a moderator. ## Ignoring Users -Commenters can ignore other commenters and essentially mute them entirely from the comment platform. Commenters can manage their ignored users list in their My Profile tab. +Commenters can ignore other commenters and essentially mute them entirely from +the comment platform. Commenters can manage their ignored users list in their My +Profile tab. ## Featured Comments -Moderators can feature comments that they want to highlight and recommend to their community. Featured comments show up on a separate tab, that is the default for the comment stream. Featured comments within the stream show a Featured badge. +Moderators can feature comments that they want to highlight and recommend to +their community. Featured comments show up on a separate tab, that is the +default for the comment stream. Featured comments within the stream show a +Featured badge. ## Sorting the Stream -Readers can sort the stream in 4 ways based on their viewing preferencet: +Readers can sort the stream in 4 ways based on their viewing preferences: * Oldest first * Newest first -* Most respect first (or most liked, most loved, etc., depending on what reactions you use) +* Most respect first (or most liked, most loved, etc., depending on what + reactions you use) * Most replied first We also make it easy to add more sorts via custom plugins. ## Badges -Badges differentiate users and comments on the stream. By default, Talk has two badges. +Badges differentiate users and comments on the stream. By default, Talk has two +badges. -The Staff user badge that shows when a commenter has an Admin, Moderator, or Staff role. +The Staff user badge that shows when a commenter has an Admin, Moderator, or +Staff role. The Featured comment badge shows when a comment has been featured. -Another optional badge is the Subscriber badge (which is available as a [Recipe]({{ "/plugin-recipes/#recipe-subscriber" | relative_url}}). +Another optional badge is the Subscriber badge (which is available as a +[Recipe]({{ "/plugin-recipes/#recipe-subscriber" | relative_url}}). -Badges are another easy part of Talk to customize by creating a new `tag`, then setting some rules for when it should show, and how the badge should be styled. +Badges are another easy part of Talk to customize by creating a new `tag`, then +setting some rules for when it should show, and how the badge should be styled. ## My Profile -The My Profile tab is where commenters can go to see their comment history, as well as reactions and replies to their comments. They can also see their email address associated with Talk, and manage their Ignored Users list here. +The My Profile tab is where commenters can go to see their comment history, as +well as reactions and replies to their comments. They can also see their email +address associated with Talk, and manage their Ignored Users list here. ## Notifications & Error Messaging -Talk leverages notification and messages on the stream to alert users to important information about their comment or their account. +Talk leverages notification and messages on the stream to alert users to +important information about their comment or their account. ### Pre-moderation of comments -If a stream is set to Pre-mod, or a commenter’s Trust karma score has fallen to negative, or if for any other reason their comment is being pre-moderated, they will get a notification letting them know this when they post a comment. +If a stream is set to Pre-mod, or a commenter’s Trust karma score has fallen to +negative, or if for any other reason their comment is being pre-moderated, they +will get a notification letting them know this when they post a comment. ### Suspension because of Username -When a commenter has been suspended because their username is inappropriate, they will see a message at the top of their streams stating this. +When a commenter has been suspended because their username is inappropriate, +they will see a message at the top of their streams stating this. ### Timed Suspension -When a commenter has been suspended for a block of time (aka a “time-out”), they will see a message at the top of their streams stating this. +When a commenter has been suspended for a block of time (aka a “time-out”), they +will see a message at the top of their streams stating this. ### Ban -When a commenter has been banned, they will see a message at the top of their streams staging this. +When a commenter has been banned, they will see a message at the top of their +streams staging this. diff --git a/docs/_docs/03-03-product-guide-moderator-features.md b/docs/_docs/03-03-product-guide-moderator-features.md index 73252de7a..45516b1a5 100644 --- a/docs/_docs/03-03-product-guide-moderator-features.md +++ b/docs/_docs/03-03-product-guide-moderator-features.md @@ -5,15 +5,21 @@ permalink: /moderator-features/ ## The Talk Admin -The Admin is your moderators will moderate your comments, and your Admins will configure and manage the different parts of Talk. +The Admin is your moderators will moderate your comments, and your Admins will +configure and manage the different parts of Talk. ### Dashboard -The Dashboard provides real-time information to moderators so they know at a glance where they should direct their attention. It shows what articles are receiving the most reports and where the most active conversations are happening. +The Dashboard provides real-time information to moderators so they know at a +glance where they should direct their attention. It shows what articles are +receiving the most reports and where the most active conversations are +happening. ### Moderate -This is the tab where Moderators will spend the majority of their time. They can choose (via the dropdown) which story they would like to moderate, or moderate site-wide. +This is the tab where Moderators will spend the majority of their time. They can +choose (via the dropdown) which story they would like to moderate, or moderate +site-wide. #### Default Mod Queues @@ -31,13 +37,15 @@ The Approved queue contains all approved comments. **Rejected** -The Rejected queue contains all comments that have been rejected, either manually by moderators or automatically, e.g. they have used a banned word. +The Rejected queue contains all comments that have been rejected, either +manually by moderators or automatically, e.g. they have used a banned word. **All** -The All queue contains all comments that have been submitted either article or site-wide. +The All queue contains all comments that have been submitted either article or +site-wide. -#### Moderation Badges +#### Moderation Badges **Pre-mod** @@ -49,11 +57,14 @@ The User badge signifies comments that have been reported by another user. **History** -The History badge signifies comments that have been flagged because of a user’s history. +The History badge signifies comments that have been flagged because of a user’s +history. **Toxic** -The Toxic badge signifies comments that are above the set Toxicity Probability Threshold. Note you must have `talk-plugin-toxic-comments` enabled. [Read more about Toxic Comments here]({{ "/toxic-comments/" | relative_url}}). +The Toxic badge signifies comments that are above the set Toxicity Probability +Threshold. Note you must have [talk-plugin-toxic-comments]({{ "/additional-plugins/#talk-plugin-toxic-comments" | relative_url }}){:.param} enabled. +[Read more about Toxic Comments here]({{ "/toxic-comments/" | relative_url}}). **Suspect** @@ -61,11 +72,13 @@ The Suspect badge signifies comments that contain a Suspect Word. **Contains Link** -The Contains Link badge signifies a comment that contains a link, which can sometimes mean it is a spam or ad comment. +The Contains Link badge signifies a comment that contains a link, which can +sometimes mean it is a spam or ad comment. **Flag Details View** -At the bottom of each comment in the moderation queues, you can see more information about a comment’s flags by clicking on More Detail. +At the bottom of each comment in the moderation queues, you can see more +information about a comment’s flags by clicking on More Detail. #### Moderator Actions @@ -79,19 +92,25 @@ Rejecting a comment removes the comment from the stream. **Feature** -Featuring a comment adds that comment to the Featured Comments tab on the stream. +Featuring a comment adds that comment to the Featured Comments tab on the +stream. **Suspend User** -Suspending a user allows a moderator to give a commenter a “time-out”; during that time they won’t be allowed to post comments or react to comments. +Suspending a user allows a moderator to give a commenter a “time-out”; during +that time they won’t be allowed to post comments or react to comments. **Ban User** -Banning a user allows a moderator to permanently disallow a commenter to interact with their community. The commenter’s previous comments will remain on the site. This action can only be un-done manually by a moderator. +Banning a user allows a moderator to permanently disallow a commenter to +interact with their community. The commenters previous comments will remain on +the site. This action can only be un-done manually by a moderator. #### Viewing a User’s Comment History -In order to get an idea of what sort of a commenter someone is, moderators can click on the commenter’s username in any moderation queue and see details about their history. +In order to get an idea of what sort of a commenter someone is, moderators can +click on the commenters username in any moderation queue and see details about +their history. **Username, Email and Member Since Date** @@ -99,23 +118,27 @@ This shows the basic details about a commenter. **Total Comments** -This shows the number of comments that a commenter has made that currently display on the site. +This shows the number of comments that a commenter has made that currently +display on the site. **Reject Rate** -This shows the % of comments a commenter has had rejected by moderators, or automatically. +This shows the % of comments a commenter has had rejected by moderators, or +automatically. **Reports** -This shows if a commenter is a reliable flagger, an unreliable flagger, or a neutral flagger. [Read more about reliable and unreliable flaggers here]({{ "/trust/#reliable-and-unreliable-flaggers" | relative_url }}). +This shows if a commenter is a reliable flagger, an unreliable flagger, or a +neutral flagger. [Read more about reliable and unreliable flaggers here]({{"/trust/#reliable-and-unreliable-flaggers" | relative_url }}). **Moderating from this View** -Talk also allows you to moderate a commenter’s recent comments from this view. +Talk also allows you to moderate a commenters recent comments from this view. #### Keyboard Shortcuts -Talk also supports a number of keyboard shortcuts that moderators can leverage to moderate quickly: +Talk also supports a number of keyboard shortcuts that moderators can leverage +to moderate quickly: | Shortcut | Action | | -------- | ------------------------------- | @@ -130,23 +153,36 @@ Talk also supports a number of keyboard shortcuts that moderators can leverage t ### Stories -In the Stories tab moderators can view all the stories that have Talk comments embedded on them, as well as be able to Open or Close comment streams on stories. +In the Stories tab moderators can view all the stories that have Talk comments +embedded on them, as well as be able to Open or Close comment streams on +stories. ### Community -The Community tab houses everything having to do with your team and your commenters. +The Community tab houses everything having to do with your team and your +commenters. #### Moderating Usernames -Any usernames that have been reported will show in the Reported Usernames sub-tab. Moderators can approve usernames if they’re suitable, or reject a username. If a username is rejected, the commenter will be notified that they need to change their username; until they do, they will be suspended from Talk. The updated username then again appears in this queue for a decision by moderators. +Any usernames that have been reported will show in the Reported Usernames +sub-tab. Moderators can approve usernames if they’re suitable, or reject a +username. If a username is rejected, the commenter will be notified that they +need to change their username; until they do, they will be suspended from Talk. +The updated username then again appears in this queue for a decision by +moderators. #### Managing People & Roles -All your team and commenters show in the People sub-tab. From here, you can manage your team members’ roles (Admins, Moderators, Staff), as well as search for commenters and take action on them (e.g. Ban/Un-ban, Suspend, etc.). -### Configure +All your team and commenters show in the People sub-tab. From here, you can +manage your team members’ roles (Admins, Moderators, Staff), as well as search +for commenters and take action on them (e.g. Ban/Un-ban, Suspend, etc.). ### +Configure See [Configuring Talk]({{ "/configuring-talk/" | relative_url }}). ## Moderating via the Comment Stream -Moderators can also choose to moderate comments in situ. If you are logged in as a Moderator or Admin, you will see a caret dropdown on each comment that allows you to Approve, Reject, or Feature comments, or Ban a User directly from the comment stream. +Moderators can also choose to moderate comments in situ. If you are logged in as +a Moderator or Admin, you will see a caret dropdown on each comment that allows +you to Approve, Reject, or Feature comments, or Ban a User directly from the +comment stream. diff --git a/docs/_docs/03-06-product-guide-configuring-talk.md b/docs/_docs/03-06-product-guide-configuring-talk.md index 3225b31bb..ba6647435 100644 --- a/docs/_docs/03-06-product-guide-configuring-talk.md +++ b/docs/_docs/03-06-product-guide-configuring-talk.md @@ -5,7 +5,8 @@ permalink: /configuring-talk/ ## Configuring an Individual Stream -There are two ways Admins can configure Talk - the first is via the Configure tab on the comment stream. +There are two ways Admins can configure Talk - the first is via the Configure +tab on the comment stream. ### Enable Pre-moderation @@ -17,18 +18,23 @@ Allows toggling of pre-moderating comments that have links. ### Ask Readers a Question & Question Icons -Admins can choose to Ask Readers a Question in order to help guide the discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/){:target="_blank"}. +Admins can choose to Ask Readers a Question in order to help guide the +discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/){:target="_blank"}. -There are a selection of icons to display different messaging other than a question on a particular stream, like an announcement, or general information about the story. +There are a selection of icons to display different messaging other than a +question on a particular stream, like an announcement, or general information +about the story. ### Closing a Stream -Closing a stream will prevent new comments. Previous comments will remain displayed on the stream for readers to view. +Closing a stream will prevent new comments. Previous comments will remain +displayed on the stream for readers to view. ## Global Configuration -Global configuration settings are available via Admin > Configure. These settings are site-wide and will affect all of your comment streams. +Global configuration settings are available via Admin > Configure. These +settings are site-wide and will affect all of your comment streams. ### Stream Settings @@ -38,7 +44,8 @@ A maximum comment length across the site. #### Comment Stream Description -Description text that will appear above every comment stream site-wide. We recommend linking to your Code of Conduct or Community Guidelines. [Read tips on how to write a Code of Conduct here](https://guides.coralproject.net/create-a-code-of-conduct/){:target="_blank"}. +Description text that will appear above every comment stream site-wide. We +recommend linking to your Code of Conduct or Community Guidelines. [Read tips on how to write a Code of Conduct here](https://guides.coralproject.net/create-a-code-of-conduct/){:target="_blank"}. #### Closed Stream Message @@ -60,11 +67,13 @@ Require new users to verify their email address prior to commenting. #### Enable Pre-moderation -Turn on pre-moderation across the site, meaning all comments will need to be moderated before they will be displayed. +Turn on pre-moderation across the site, meaning all comments will need to be +moderated before they will be displayed. #### Pre-moderate Comments Containing Links -Turn on pre-moderation for comments with links across the site, meaning all comments with links will need to be moderated before they will be displayed. +Turn on pre-moderation for comments with links across the site, meaning all +comments with links will need to be moderated before they will be displayed. #### Banned Words List @@ -72,12 +81,15 @@ A list of words that will trigger a comment to be automatically Rejected. #### Suspect Words List -A list of words that will trigger a comment to be automatically Reported. Comments with suspect words will display until a moderator takes action on them. +A list of words that will trigger a comment to be automatically Reported. +Comments with suspect words will display until a moderator takes action on them. ### Technical Settings #### Permitted Domains -A list of domains where your Talk instance is allowed to be embedded. Typical use is `localhost`, `staging.yourdomain.com`, `yourdomain.com`, etc. + +A list of domains where your Talk instance is allowed to be embedded. Typical +use is `localhost`, `staging.yourdomain.com`, `yourdomain.com`, etc. #### Embed Script @@ -85,4 +97,5 @@ This is the unique Talk script that is to be used to embed Talk on your website. #### Custom CSS URL -The link to your custom stylesheet for Talk. This will override any default styles, so you can make Talk your own! +The link to your custom stylesheet for Talk. This will override any default +styles, so you can make Talk your own! diff --git a/docs/_docs/05-01-faq.md b/docs/_docs/05-01-faq.md index c084bc903..06d0b0669 100644 --- a/docs/_docs/05-01-faq.md +++ b/docs/_docs/05-01-faq.md @@ -5,7 +5,8 @@ permalink: /faq/ ## How can I get help integrating Talk into my newsroom? -We're here to help with newsrooms of all sizes. Email our Integration Engineer (jeff@mozillafoundation.org) to set up a meeting. +We're here to help with newsrooms of all sizes. Email our Integration Engineer +([jeff@mozillafoundation.org](mailto:jeff@mozillafoundation.org)) to set up a meeting. ## How do I request a feature or submit a bug?