[ADD] forum: create the forum documentation

This PR adds a page describing how to create, use and moderate a forum.
It creates references in the elearning page as karma features are shared.
It removes redundant information from the helpdesk/overview/help_center
page and links back to the more detailed forum page.

task-3283274

closes odoo/documentation#5676

X-original-commit: c60ec48c9d
Signed-off-by: Xavier Platteau (xpl) <xpl@odoo.com>

content/applications/services/helpdesk/overview/help_center.rst

@@ -2,7 +2,7 @@
 Help center
 ===========
 
-Odoo *Helpdesk* integrates with the *Forums*, *eLearning*, and *Knowledge* apps to create the *help
+Odoo *Helpdesk* integrates with the *Forum*, *eLearning*, and *Knowledge* apps to create the *help
 center*.
 
 .. image:: help_center/help-center-enable-features.png
@@ -171,6 +171,8 @@ make any necessary additions or edits to the template, then click :guilabel:`Sen
    Doing so will not replace the existing text in a ticket's description. The template will be added
    as additional text.
 
+.. _helpdesk/forum:
+
 Community Forum
 ===============
 
@@ -199,91 +201,9 @@ menu to enable that forum.
 To create a new forum, type a name into the blank :guilabel:`Forums` field, then click the
 :guilabel:`Create and Edit` option. Multiple forums can be selected in this field.
 
-Set up a forum
---------------
-
-The settings on a forum are managed through either the *Website* or *eLearning* applications. From
-the Odoo Dashboard, navigate to :menuselection:`Website --> Configuration --> Forums` or
-:menuselection:`eLearning --> Forum --> Forums`. In either case, select a forum to edit from the
-list.
-
-On the forum detail form, select a mode.
-
-The :guilabel:`Questions` mode allows for one answer/response for each post, while
-:guilabel:`Discussion` mode allows for multiple responses. To limit the forum to a single website,
-select it from the :guilabel:`Website` field.
-
-Under the :guilabel:`Order and Visibility` section, in the :guilabel:`Options` tab, choose how the
-posts should be sorted, by modifying the :guilabel:`Default Sort` field. Change the
-:guilabel:`Privacy` setting to change which users will have access to the forum.
-
-Below these settings, there is space to add a description for the forum. This description will be
-visible on the website where the forum is published.
-
-.. image:: help_center/help-center-forum-settings.png
-   :align: center
-   :alt: Overview of a forum's settings page in Odoo Helpdesk.
-
-Karma gains and karma related rights
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When users interact on forums - either through posting questions, submitting answers, or upvoting
-responses - they earn points, called *karma*.
-
-Karma points are used to build the credibility of a user within the community. The more positive
-interactions a user has on the forum, the more karma points they gain. Certain activities, such as
-posting without validation, or editing posts, require users to have earned a specific level of karma
-points to prove their legitimacy and trustworthiness.
-
-These figures can be adjusted on the :guilabel:`Karma gains` and :guilabel:`Karma related rights`
-tabs, located on the forums detail form.
-
-.. tabs::
-
-   .. tab:: Karma gains
-
-      In the :guilabel:`Karma gains` tab, there are listed actions that will cause users to gain
-      (or lose) karma points. Those actions are:
-
-      - Asking a question
-      - Question upvoted
-      - Question downvoted
-      - Answer upvoted
-      - Answer downvoted
-      - Accepting an answer
-      - Answer accepted
-      - Answer flagged
-
-   .. tab:: Karma related rights
-
-      In the :guilabel:`Karma related rights` tab, there are listed activities that users cannot
-      complete, without having a specific level of karma points. Those activities are:
-
-      - Ask questions
-      - Answer questions
-      - Upvote
-      - Downvote
-      - Edit own posts
-      - Edit all posts
-      - Close own posts
-      - Close all posts
-      - Delete own posts
-      - Delete all posts
-      - Nofollow links
-      - Accept an answer on own question
-      - Accept an answer to all questions
-      - Editor features: image and links
-      - Comment on own posts
-      - Comment on all posts
-      - Convert own answers to comments (and vice versa)
-      - Convert all answers to comments (and vice versa)
-      - Unlink own comments
-      - Unlink all comments
-      - Ask questions without validation
-      - Flag a post as offensive
-      - Moderate posts
-      - Change question tags
-      - Create new tags
+.. seealso::
+   Check out the :doc:`Forum documentation <../../../websites/forum>` to learn how to configure,
+   use, and moderate a forum.
 
 Create a forum post from a Helpdesk ticket
 ------------------------------------------

content/applications/websites.rst

@@ -10,4 +10,5 @@ Websites
     websites/website
     websites/ecommerce
     websites/elearning
+    websites/forum
     websites/livechat

content/applications/websites/elearning.rst

@@ -214,6 +214,8 @@ It appears in the course content on your website.
   :align: center
   :alt: Additional ressources
 
+.. _elearning/quiz:
+
 Quiz tab
 --------
 

content/applications/websites/forum.rst

@@ -0,0 +1,402 @@
+=====
+Forum
+=====
+
+**Odoo Forum** is a question-and-answer forum designed with providing customer support in mind.
+Adding a forum to a website enables you to build a community, encourage engagement, and share
+knowledge.
+
+.. _forum/create:
+
+Create a forum
+==============
+
+To create or edit a forum, go to :menuselection:`Website --> Configuration --> Forum: Forums`. Click
+:guilabel:`New` or select an existing forum and configure the following elements.
+
+:guilabel:`Forum Name`: add the name of the forum.
+
+:guilabel:`Mode`: select :guilabel:`Questions` to enable marking an answer as best, meaning
+questions then appear as *solved*, or :guilabel:`Discussions` if the feature is not needed.
+
+.. note::
+   Regardless of the selected mode, only **one answer** per user is allowed on a single post.
+   Commenting multiple times is allowed, however.
+
+:guilabel:`Default Sort`: choose how questions are sorted by default.
+
+  - :guilabel:`Newest`: by latest question posting date
+  - :guilabel:`Last Updated`: by latest posting activity date (answers and comments included)
+  - :guilabel:`Most Voted`: by highest vote tally
+  - :guilabel:`Relevance`: by post relevancy (determined by a formula)
+  - :guilabel:`Answered`: by likelihood to be answered (determined by a formula)
+
+.. note::
+   Users have several sorting options (total replies, total views, last activity) on the forum
+   front end.
+
+:guilabel:`Privacy`: select :guilabel:`Public` to let anyone view the forum, :guilabel:`Signed In`
+to make it visible only for signed-in users, or :guilabel:`Some users` to make it visible only for a
+specific user access group by selecting one :guilabel:`Authorized Group`.
+
+Next, configure the :ref:`karma gains <forum/karma-gains>` and the :ref:`karma-related rights
+<forum/karma-related-rights>`.
+
+.. _forum/karma:
+
+Karma points
+------------
+
+Karma points can be given to users based on different forum interactions. They can be used to
+determine which forum functionalities users can access, from being able to vote on posts to
+having moderator rights. They are also used to set user :ref:`ranks <forum/ranks>`.
+
+.. important::
+   - A user's karma points are shared across all forums, courses, etc., of a single Odoo website.
+   - eLearning users can earn karma points through different :ref:`course interactions
+     <elearning/karma>` and by :ref:`completing quizzes <elearning/quiz>`.
+
+.. _forum/karma-gains:
+
+Karma gains
+~~~~~~~~~~~
+
+Several forum interactions can give or remove karma points.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Interaction
+     - Description
+     - Default karma gain
+   * - :guilabel:`Asking a question`
+     - You post a question.
+     - 2
+   * - :guilabel:`Question upvoted`
+     - Another user votes for a question you posted.
+     - 5
+   * - :guilabel:`Question downvoted`
+     - Another user votes against a question you posted.
+     - -2
+   * - :guilabel:`Answer upvoted`
+     - Another user votes for an answer you posted.
+     - 10
+   * - :guilabel:`Answer downvoted`
+     - Another user votes against an answer you posted.
+     - -2
+   * - :guilabel:`Accepting an answer`
+     - You mark an answer posted by another user as best.
+     - 2
+   * - :guilabel:`Answer accepted`
+     - Another user marks an answer you posted as best.
+     - 15
+   * - :guilabel:`Answer flagged`
+     - A question or an answer you posted is :ref:`marked as offensive <forum/moderation>`.
+     - -100
+
+.. note::
+   New users receive **three points** upon validating their email address.
+
+To modify the default values, go to :menuselection:`Website --> Configuration --> Forum: Forums`,
+select the forum, and go to the :guilabel:`Karma Gains` tab. Select a value to edit it.
+
+If the value is positive (e.g., `5`), the number of points will be added to the user's tally each
+time the interaction happens on the selected forum. Conversely, if the value is negative (e.g.,
+`-5`), the number of points will be deducted. Use `0` if an interaction should not impact a user's
+tally.
+
+.. _forum/karma-related-rights:
+
+Karma-related rights
+~~~~~~~~~~~~~~~~~~~~
+
+To configure how many karma points are required to access the different forum functionalities, go
+to :menuselection:`Website --> Configuration --> Forum: Forums`, select the forum, and go to the
+:guilabel:`Karma Related Rights` tab. Select a value to edit it.
+
+.. warning::
+   Some functionalities, such as :guilabel:`Edit all posts`, :guilabel:`Close all posts`,
+   :guilabel:`Delete all posts`, :guilabel:`Moderate posts`, and :guilabel:`Unlink all comments`,
+   are rather sensitive. Make sure to understand the consequences of giving *any* user reaching the
+   set karma requirements access to such functionalities.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Functionality
+     - Description
+     - Default karma requirement
+   * - :guilabel:`Ask questions`
+     - Post questions.
+     - 3
+   * - :guilabel:`Answer questions`
+     - Post answers to questions.
+     - 3
+   * - :guilabel:`Upvote`
+     - Vote for questions or answers.
+     - 5
+   * - :guilabel:`Downvote`
+     - Vote against questions or answers.
+     - 50
+   * - :guilabel:`Edit own posts`
+     - Edit questions or answers you posted.
+     - 1
+   * - :guilabel:`Edit all posts`
+     - Edit any question or answer.
+     - 300
+   * - :guilabel:`Close own posts`
+     - Close questions or answers you posted.
+     - 100
+   * - :guilabel:`Close all posts`
+     - Close any question or answer.
+     - 500
+   * - :guilabel:`Delete own posts`
+     - Delete questions or answers you posted.
+     - 500
+   * - :guilabel:`Delete all posts`
+     - Delete any question or answer.
+     - 1,000
+   * - :guilabel:`Nofollow links`
+     - If you are under the karma threshold, a *nofollow* attribute tells search engines to ignore
+       links you post.
+     - 500
+   * - :guilabel:`Accept an answer on own questions`
+     - Mark an answer as best on questions you posted.
+     - 20
+   * - :guilabel:`Accept an answer to all questions`
+     - Mark an answer as best on any question.
+     - 500
+   * - :guilabel:`Editor Features: image and links`
+     - Add links and images to your posts.
+     - 30
+   * - :guilabel:`Comment own posts`
+     - Post comments under questions or answers you created.
+     - 1
+   * - :guilabel:`Comment all posts`
+     - Post comments under any question or answer.
+     - 1
+   * - :guilabel:`Convert own answers to comments and vice versa`
+     - Convert comments you posted as answers.
+     - 50
+   * - :guilabel:`Convert all answers to comments and vice versa`
+     - Convert any comment as answer.
+     - 500
+   * - :guilabel:`Unlink own comments`
+     - Delete comments you posted.
+     - 50
+   * - :guilabel:`Unlink all comments`
+     - Delete any comment.
+     - 500
+   * - :guilabel:`Ask questions without validation`
+     - Questions you post do not require to be :ref:`validated <forum/moderation>` first.
+     - 100
+   * - :guilabel:`Flag a post as offensive`
+     - Flag a question or answer as offensive.
+     - 500
+   * - :guilabel:`Moderate posts`
+     - Access all :ref:`moderation tools <forum/moderation>`.
+     - 1,000
+   * - :guilabel:`Change question tags`
+     - Change posted questions' :ref:`tags <forum/tags>` (if you have the right to edit them).
+     - 75
+   * - :guilabel:`Create new tags`
+     - Create new :ref:`tags <forum/tags>` when posting questions.
+     - 30
+   * - :guilabel:`Display detailed user biography`
+     - When a user hovers their mouse on your avatar or username, a popover box showcases your
+       karma points, biography, and number of :ref:`badges <forum/badges>` per level.
+     - 750
+
+.. tip::
+   Track all karma-related activity and add or remove karma manually by :ref:`enabling developer
+   mode <developer-mode>` and going to :menuselection:`Settings --> Gamification Tools --> Karma
+   Tracking`.
+
+.. _forum/gamification:
+
+Gamification
+------------
+
+Ranks and badges can be used to encourage participation. Ranks are based on the total :ref:`karma
+points <forum/karma>`, while badges can be granted manually or automatically by completing
+challenges.
+
+.. _forum/ranks:
+
+Ranks
+~~~~~
+
+To create new ranks or modify the default ones, go to :menuselection:`Website --> Configuration -->
+Forum: Ranks` and click :guilabel:`New` or select an existing rank.
+
+Add the :guilabel:`Rank Name`, the :guilabel:`Required Karma` points to reach it, its
+:guilabel:`Description`, a :guilabel:`Motivational` message to encourage users to reach it, and an
+image.
+
+.. image:: forum/ranks.png
+   :alt: Default forum ranks
+
+.. _forum/badges:
+
+Badges
+~~~~~~
+
+To create new badges or modify the default ones, go to :menuselection:`Website --> Configuration -->
+Forum: Badges` and click :guilabel:`New` or select an existing badge.
+
+Enter the badge name and description, add an image, and configure it.
+
+Assign manually
+***************
+
+If the badge should be granted manually, select which users can grant them by selecting one of the
+following :guilabel:`Allowance to Grant` options:
+
+- :guilabel:`Everyone`: all non-portal users (since badges are granted from the backend).
+- :guilabel:`A selected list of users`: users selected under :guilabel:`Authorized Users`.
+- :guilabel:`People having some badges`: users who have been granted the badges selected under
+  :guilabel:`Required Badges`.
+
+It is possible to restrict how many times per month each user can grant the badge by enabling
+:guilabel:`Monthly Limited Sending` and entering a :guilabel:`Limitation Number`.
+
+Assign automatically
+********************
+
+If the badge should be granted **automatically** when certain conditions are met, select
+:guilabel:`No one, assigned through challenges` under :guilabel:`Allowance to Grant`.
+
+Next, determine how the badge should be granted by clicking :guilabel:`Add` under the
+:guilabel:`Rewards for challenges` section. Select a challenge to add it or create one by clicking
+:guilabel:`New`.
+
+.. tip::
+   It is possible to give the badge a :guilabel:`Forum Badge Level` (:guilabel:`Bronze`,
+   :guilabel:`Silver`, :guilabel:`Gold`) to give it more or less importance.
+
+.. image:: forum/badges.png
+   :alt: Default forum badges
+
+.. _forum/tags:
+
+Tags
+----
+
+Users can use tags to filter forum posts.
+
+To manage tags, go to :menuselection:`Website --> Configuration --> Forum: Tags`. Click
+:guilabel:`New` to create a tag and select the related :guilabel:`Forum`.
+
+.. tip::
+   - Use the :guilabel:`Tags` section on the forum's sidebar to filter all questions assigned to the
+     selected tag. Click :guilabel:`View all` to display all tags.
+   - New tags can be created when posting a new message, provided the user has enough :ref:`karma
+     points <forum/karma-related-rights>`.
+
+.. _forum/use:
+
+Use a forum
+===========
+
+.. note::
+   Access to many functionalities depends on a user's :ref:`karma points
+   <forum/karma-related-rights>`.
+
+.. _forum/post:
+
+Post questions
+--------------
+
+To create a new post, access the forum's front end, click :guilabel:`New Post`, and fill in the
+following:
+
+- :guilabel:`Title`: add the question or the topic of the post.
+- :guilabel:`Description`: add a description for the question.
+- :guilabel:`Tags`: add up to five :ref:`tags <forum/tags>`.
+
+Click :guilabel:`Post Your Question`.
+
+.. _forum/interact:
+
+Interact with posts
+-------------------
+
+Different actions are possible on a post.
+
+- Mark a question as **favorite** by clicking the star button (:guilabel:`☆`).
+- Follow a post and get **notifications** (by email or within Odoo) when it is answered by clicking
+  the bell button (:guilabel:`🔔`).
+- **Vote** *for* (up arrow :guilabel:`▲`) or *against* (down arrow :guilabel:`▼`) a question or
+  answer.
+- Mark an answer as **best** by clicking the check mark button (:guilabel:`✔`). This option is only
+  available if the :guilabel:`Forum Mode` is set to :guilabel:`Questions`.
+- :guilabel:`Answer` a question.
+- **Comment** on a question or answer by clicking the speech bubble button (:guilabel:`💬`).
+- **Share** a question on Facebook, Twitter, or LinkedIn by clicking the *share nodes* button.
+
+Click the ellipsis button (:guilabel:`...`) to:
+
+  - :guilabel:`Edit` a question or answer.
+  - :guilabel:`Close` a question.
+  - :guilabel:`Delete` a question, answer, or comment. It is possible to :guilabel:`Undelete`
+    questions afterward.
+  - :guilabel:`Flag` a question or answer as offensive.
+  - :guilabel:`Convert` a comment into an answer.
+  - :guilabel:`View` the related :ref:`Helpdesk ticket <helpdesk/forum>`, if any.
+
+.. image:: forum/post-actions.png
+   :alt: Posts actions
+
+.. note::
+   By default, 150 karma points are required to view another user's profile. This value can be
+   configured when creating a new website.
+
+.. _forum/moderation:
+
+Moderate a forum
+================
+
+On the forum's front end, the sidebar's :guilabel:`Moderation tools` section gathers the essential
+moderator functionalities.
+
+.. image:: forum/moderation-tools.png
+   :alt: Forum sidebar moderation tools
+
+:guilabel:`To Validate`: access all questions and answers waiting for validation before being
+displayed to non-moderator users.
+
+.. image:: forum/to-validate.png
+   :alt: Question to validate
+
+.. note::
+   A question is pending if a user does not have the required karma. The user is not able to post
+   questions or answers while awaiting validation. Only one pending question per user is allowed per
+   forum.
+
+:guilabel:`Flagged`: access all questions and answers that have been flagged as offensive. Click
+:guilabel:`Accept` to remove the offensive flag or :guilabel:`Offensive` to confirm it, then select
+a reason and click :guilabel:`Mark as offensive`. The post is then hidden from users without
+moderation rights, and 100 karma points are deducted from the offending user's tally.
+
+.. image:: forum/offensive-reason.png
+   :alt: Offensive reason selection
+
+:guilabel:`Closed`: access all questions that have been closed. It is possible to :guilabel:`Delete`
+or :guilabel:`Reopen` them. To close a question, open it, click the ellipsis button
+(:guilabel:`...`), then :guilabel:`Close`, select a :guilabel:`Close Reason`, and click
+:guilabel:`Close post`. The post is then hidden from users without moderation rights.
+
+.. note::
+   When selecting :guilabel:`Spam or advertising` or :guilabel:`Contains offensive or malicious
+   remarks` as the reason, 100 karma points are deducted from the poster's tally.
+
+.. tip::
+   - Create and edit close reasons by going to :menuselection:`Website --> Configuration --> Forum:
+     Close Reasons`. Select :guilabel:`Basic` as :guilabel:`Reason Type` if the reason should be
+     used when closing a question, and :guilabel:`Offensive` if it should be used for flagged posts.
+   - Manage all posts by going to :menuselection:`Website  --> Configuration --> Forum: Forums`,
+     selecting the forum, and clicking the :guilabel:`Posts` smart button. By clicking the
+     :guilabel:`Actions` button, it is possible to :guilabel:`Export`, :guilabel:`Archive`,
+     :guilabel:`Unarchive`, or :guilabel:`Delete` one or multiple posts.