Merge pull request #2178 from openedx/sundas/INF-955

docs: updated documentation of section 17.1.3

en_us/shared/manage_discussions/discussions.rst

@@ -1,8 +1,7 @@
 .. _Discussions:
 
-##################################
 Creating Course Discussions
-##################################
+###########################
 
 Discussions in an edX course include both course-wide topics of interest to
 all learners (such as "Feedback", "Troubleshooting", or "Technical Help") as
@@ -26,7 +25,6 @@ For information about running and moderating course discussions, see
 
 .. _Configuring Edx Discussions:
 
-****************************
 Configuring Edx Discussions
 ****************************
 
@@ -58,11 +56,8 @@ for edx discussions can be found here.
   :width: 300
   :alt: Appearance of edx discussions configurations page.
 
-
-
 .. _Create CourseWide Discussion Topics:
 
-*************************************
 Create Course-Wide Discussion Topics
 *************************************
 
@@ -117,19 +112,94 @@ Discussion list now includes the topic you added.
 
 .. _Create ContentSpecific Discussion Topics:
 
-*********************************************
 Create Content-Specific Discussion Topics
 *********************************************
 
+Course runs created on or after May 16, 2023, use an upgraded version of
+the edX discussion forum. Learn more about it `here`_. The creation of content-specific discussion topics for both the legacy and the upgraded versions
+of the discussion forums are explained separately in the sections below.
+
+.. _here: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3470655498/Discussions+upgrade+Sidebar+and+new+topic+structure.
+
+Upgraded Edx Forum
+==================
+
+Discussion can be enabled for a course unit, which is equivalent to adding
+a content-specific discussion topic in that unit in the legacy version of
+the forum. To enable discussion on a course unit:
+
+1. Open unit’s configuration in Studio.
+
+2. Check the **Enable discussion** checkbox.
+
+.. image:: ../../../shared/images/enable-discussion.png
+  :width: 700
+  :align: center
+  :alt: Toggle switches for anonymous posts in edx discussions configuration.
+
+3. Click **Save**.
+
+Discussions will be enabled on the unit within 1 minute. Units that have
+discussions enabled for them will show a **Discussion enabled** label in Studio.
+
+.. image:: ../../../shared/images/discussion-enabled.png
+  :width: 700
+  :align: center
+  :alt: Toggle switches for anonymous posts in edx discussions configuration.
+
+.. note:: To enable discussion for units in subsections marked as graded (but
+  not **Timed Exams**), first enable the **Enable discussions on units in graded
+  subsusections** toggle on discussion configuration page in studio (see :ref:`Configuring Edx Discussions`).
+
+.. note:: Discussions can not be enabled for units belonging to subsections marked
+  as **Timed Exams**.
+
+Users can participate in these discussions using the **Discussion** tab or via the
+discussion sidebar visible alongside the course unit.
+
+.. image:: ../../../shared/images/discussion-sidebar.png
+  :width: 300
+  :align: center
+  :alt: Toggle switches for anonymous posts in edx discussions configuration.
+
+To disable discussion for a unit, uncheck the **Discussion enabled** checkbox in the
+unit’s configuration and click **Save**.
+
+If the discussion topic for this unit contains at least 1 discussion thread, it
+will appear under the **Archived** section in the **Topics** tab in the **Discussion**
+tab. Otherwise it will be deleted.
+
+If discussion is enabled again for this unit, the archived topic will be restored along
+with the threads contained within it.
+
+.. image:: ../../../shared/images/archived.png
+  :width: 300
+  :height: 400
+  :alt: Toggle switches for anonymous posts in edx discussions configuration.
+
+.. warning:: If **Enable discussions on units in graded subsections** toggle on
+  the discussion configuration page (see :ref:`Configuring Edx Discussions`) is turned
+  off, any discussion topics associated with units belonging to graded subsections
+  will be archived or deleted (if they don’t contain any threads). Enabling the
+  toggle again will restore archived topics and replace deleted topics with new ones.
+
+.. warning:: If a subsection is marked as **Timed Exam**, any discussion topics associated
+  with units belonging to this subsection will be archived or deleted (if they don’t
+  contain any threads). Un-marking the subsection will restore archived topics and
+  replace deleted topics with new ones.
+
+Legacy Edx Forum
+==================
+
 To create a content-specific discussion topic, you add a discussion component
 to a unit. Typically, you do this while you are designing and creating your
 course in Studio. Follow the instructions in :ref:`Working with Discussion
 Components`. The result is a discussion topic associated with a unit and its
 content. Learners can access content-specific topics both in the course unit
-and on the **Discussion** page.
+and on the Discussion page.
 
 .. warning:: Follow the recommended steps to add discussion components. Do not
-   create discussion topics by using the **Duplicate** button in Studio, and do
+   create discussion topics by using the Duplicate button in Studio, and do
    not reference the same discussion ID in more than one place in your course.
    Duplicated discussion components result in discussion topics that contain the
    same conversations, even if learners post in different discussion topics.
@@ -144,20 +214,18 @@ topics, see :ref:`Visibility of Discussion Topics`.
    of the same group can see and respond to each other's posts. For information,
    see :ref:`Divide All Content Specific Discussion Topics`.
 
-
 .. _Visibility of Discussion Topics:
 
-*********************************************************
 Understanding When Learners Can See Discussion Topics
 *********************************************************
 
 The names that you specify as the category and subcategory names for discussion
-components are not visible on the **Discussion** page in the LMS until after
+components are not visible on the Discussion page in the LMS until after
 the course has started and the unit is released.
 
 However, "seed" posts that you create in content-specific discussion topics
 before a course starts, or before the unit is released, are immediately visible
-on the **Discussion** page, even though the containing category or subcategory
+on the Discussion page, even though the containing category or subcategory
 names are not visible. EdX recommends that you do not create posts in
 content-specific discussion topics before a unit is released. For more
 information about release dates and the visibility of components, see
@@ -173,43 +241,38 @@ release dates.
 
 .. _Anonymous_posts:
 
-*****************************************************
 Allowing Learners to Make Anonymous Discussion Posts
 *****************************************************
 
 By default, when learners participate in a discussion, their usernames are
 visible in the discussion. You can allow learners to make discussion posts
-that are anonymous i.e. their usernames are not visible. You can also choose
-whether the anonymous posts that learners make are anonymous only to their
-peers or to the course staff as well.
+that are anonymous to other learners i.e. their usernames are not visible
+to other learners.
 
 To allow anonymous discussion posts in your course, follow these steps.
 
 1. Navigate to edx discussion configuration page
 (see :ref:`Configuring Edx Discussions`).
 
-2. Toggle the **Allow anonymous discussion posts** to enable learner make
-posts that are anonymous to everyone.
+2. Toggle the **Allow anonymous discussion posts to peers** to enable learners to
+make posts that are anonymous to everyone other learners.
 
-3. Once anonymous posts are enabled, you can toggle **Allow anonymous discussion posts to peers**
-to allow learners to make posts that are anonymous to their peers, but not to the course staff.
-
- .. image:: ../../../shared/images/Toggle_switch_anonymous_posts.png
-  :width: 300
+ .. image:: ../../../shared/images/anonymous-posting.png
+  :width: 400
   :alt: Toggle switches for anonymous posts in edx discussions configuration.
 
-4. Click **Save**.
+3. Click **Save**.
 
-Users see the `post anonymously` and `post anonymously to classmates` options while creating a
-post if toggles in step 2 and step 3 have been enabled, respectively, as seen below.
+Once the toggle has been enabled, forum users will have the option to create posts
+that are anonymous to other learners, as seen below.
 
- .. image:: ../../../shared/images/anonymous_option_creating_a_post.png
-  :width: 300
+ .. image:: ../../../shared/images/post-anonymously.png
+  :width: 600
+  :align: center
   :alt: Options for anonymous posting while creating a post.
 
 .. _Discussions on Mobile Apps:
 
-**********************************
 Discussions in the edX Mobile App
 **********************************