Merge pull request #4372 from edx/ahodges/documentation/discussionoverview

New chapter on discussion features for all users

docs/en_us/course_authors/source/change_log.rst

@@ -13,6 +13,8 @@ July, 2014
 
    * - Date
      - Change
+   * - 07/15/14
+     - Added the :ref:`Discussions for Students and Staff` chapter.
    * - 07/11/14
      - Added :ref:`Track Student Activity` to the :ref:`Student Data`
        chapter.

docs/en_us/course_authors/source/running_course/discussions.rst

@@ -43,17 +43,21 @@ levels of interaction.
   directly to a post to provide a solution or continue the conversation.
 
 * A *comment* is the third level of interaction. A comment is often a
-  clarification or side note made to a specific reponse, rather than to the
+  clarification or side note made to a specific response, rather than to the
   post as a whole.
  
 The dialog created by a post, its responses, and the comments on those
 repsonses is called a *thread*.
 
-All course staff members and enrolled students can add posts, reponses, and
+All course staff members and enrolled students can add posts, responses, and
 comments, and view all of the posts, responses, and comments made by other
 course participants. Discussion threads are saved as part of the course
 history.
 
+..note:: 
+ The :ref:`Discussions for Students and Staff` section describes features that
+ are available to all discussion participants. 
+
 .. _Organizing_discussions:
 
 *************************************************

docs/en_us/course_authors/source/running_course/discussions_students.rst

+.. _Discussions for Students and Staff:
+
+###############################################
+Participating in Course Discussions
+###############################################
+
+.. please suggest a better title ^^ for this section!
+
+Course discussions give you the opportunity to start conversations with other
+students, ask questions of the course team, and participate in the course
+community.
+
+Features of edX discussions that can make your participation more effective
+include ways to:
+
+* :ref:`Find Posts`
+
+* :ref:`Keep Up with New Activity`
+
+* :ref:`Follow Posts`
+
+* :ref:`Vote for Posts or Responses`
+
+* :ref:`Report Discussion Misuse`
+
+.. _Find Posts:
+
+==================
+Find Posts
+==================
+
+Finding out whether someone else has already started a conversation about the
+subject you're interested in, and then reading and contributing to that
+exchange instead of starting a new one, helps make course discussions more
+productive for everyone. You can search for something specific or you can
+browse through the posts in a single discussion topic.
+
+Search the Discussions
+****************************
+
+To search for text, click **Discussion** and enter a phrase, a word, or part of
+a word in the **Search all posts** field above the list of posts. When you
+press Enter, the search tries to find:
+
+* A match or close match to your text in any post, response, or comment. The
+  display updates to show a list of the posts that have a match at any level of
+  interaction.
+
+* A similar value in any post, response, or comment (if no exact matches are
+  found). A "No results found for {text}. Showing results for {similar}" message
+  displays above the posts that have similar text at any interaction level.
+
+* Any usernames that are an exact match to your text. A "Show posts by
+  {username}" option displays above any posts that have an exact match at any
+  interaction level. Click the username in the message to read that user's
+  posts, responses, and comments.
+
+Review Posts About a Single Topic
+**************************************
+
+To review posts about a particular part of the course or type of issue, click
+**Discussion** at the top of the page and then select a topic from the drop-down
+list. (**All Discussions** is selected by default.) Only posts about the topic
+you select appear in the list of posts.
+
+.. _Keep Up with New Activity:
+
+===========================
+Keep Up with New Activity
+===========================
+
+Read New or Updated Posts
+***********************************
+
+The list of posts provides visual cues to help you identify posts that are new,
+or that have responses or comments that you have not read yet, and to
+distinguish them from exchanges that you have already read completely.
+
+* Posts that you have not read yet have a blue dialog "bubble".
+
+* Posts with responses or comments that you have not read yet have a white
+  dialog "bubble".
+ 
+* Exchanges that you have read completely have a gray dialog "bubble" and
+  background.
+
+ .. image:: ../Images/Discussion_colorcoding.png
+  :alt: The list of posts with posts showing differently colored backgrounds and bubble icons
+
+These color-coded dialog bubbles appear when you sort the list of posts by
+recent activity or by most activity. If you sort the list of posts by most votes
+instead, the number of votes that the post has received appears in place of the
+bubble icon. See :ref:`Vote for Posts or Responses`.
+
+Receive Daily Digests
+***********************
+
+You have the option to receive an email message each day that summarizes
+discussion activity for the posts you are following. To receive this daily
+digest, click **Discussion** and then select the **Receive updates** checkbox.
+
+.. _Follow Posts:
+
+=====================
+Follow Posts
+=====================
+
+If you find a post particularly interesting and want to return to it in the
+future, you can follow it: view that post and click the star icon in its top
+right corner.
+
+.. image:: ../Images/Discussion_follow.png
+ :alt: A post with the Follow icon circled
+
+Each post that you follow appears with a "Following" badge in the list of
+posts.
+
+To list only the posts that you are following, regardless of the discussion
+topic they apply to, click the drop-down Discussion list and select
+**Posts I'm Following**.
+
+.. image:: ../Images/Discussion_filterfollowing.png
+ :alt: The list of posts with the "Posts I'm Following" filter selected. Every post shows the following badge.
+
+.. _Vote for Posts or Responses:
+
+===========================
+Vote for Posts or Responses
+===========================
+
+If you like a post or one of its responses, you can vote for it: view the
+post or response and click the **+** at top right.
+
+.. image:: ../Images/Discussion_vote.png
+ :alt: A post with the Vote icon circled
+
+You can sort the list of posts so that the posts with the most votes appear at
+the top: click the drop-down list of sorting options and select **by most
+votes**.
+
+.. image:: ../Images/Discussion_sortvotes.png
+ :alt: The list of posts with the "by most votes" sorting option and the number of votes for the post circled
+
+The number of votes that each post has received displays in the list of posts.
+(Votes for responses are not included in the number.)
+
+.. _Report Discussion Misuse:
+
+===========================
+Report Discussion Misuse
+===========================
+
+You can flag any post, response, or comment for a discussion moderator to
+review: view the post or response and then click **Report Misuse**. For a
+comment, click the flag.
+
+.. image:: ../Images/Discussion_reportmisuse.png
+ :alt: A post and a response with the "Report Misuse" link circled, and a comment with the flag icon circled
+
+.. Future: DOC-121 As a course author, I need a template of discussion guidelines to give to students
\ No newline at end of file

docs/en_us/course_authors/source/running_course/index.rst

@@ -10,6 +10,7 @@ Running Your Course
    course_staffing
    course_enrollment
    discussions
+   discussions_students
    discussion_guidance_moderators
    course_data
    course_student