Merge pull request #4483 from edx/ahodges/documentation/FOR662

Ahodges/documentation/for662

docs/en_us/course_authors/source/Format Cheat Sheet.rstnouse

@@ -101,11 +101,17 @@ To make the cross reference in text:
 
         see :ref:`Set Grade Brackets<Set-Grade-Brackets>`
 
-To cross-reference a topic, but use your own text instead of the topic title, use the :ref: directive, but enter your own text followed by the topic anchor in angle brackets:
+To cross-reference a topic, but use your own text instead of the topic title,
+use the :ref: directive, but enter your own text followed by the topic anchor in
+angle brackets:
 
-        If you want to add a graded tool or exercise, add the tool as a :ref:`custom JavaScript problem<Custom JavaScript>` or an :ref:`LTI component<LTI Component>`.
+        If you want to add a graded tool or exercise, add the tool as a
+        :ref:`custom JavaScript problem<Custom JavaScript>` or an :ref:`LTI
+        component<LTI Component>`.
 
-        (In this sentence, the text appears as "custom JavaScript problem" and "LTI component", and the linked-to topic titles are "Custom JavaScript Problem" and "LTI Component".)
+        (In this sentence, the text appears as "custom JavaScript problem" and
+        "LTI component", and the linked-to topic titles are "Custom JavaScript
+        Problem" and "LTI Component".)
 
 External page reference
 

docs/en_us/course_authors/source/change_log.rst

@@ -13,6 +13,9 @@ July, 2014
 
    * - Date
      - Change
+   * - 07/30/14
+     - Expanded the :ref:`Discussions for Students and Staff` chapter to
+       include information about adding posts, responses, and comments.
    * - 07/23/14
      - Added the section :ref:`Grade Ranges and Certificates` to the
        :ref:`Establish a Grading Policy` chapter.

docs/en_us/course_authors/source/creating_content/create_discussion.rst

@@ -44,10 +44,21 @@ Private Units`.
    .. image:: ../Images/Disc_Create_Edit.png
     :alt: Image of the discussion component with the Edit button circled
 
-#. When the Discussion component editor opens, follow the guidelines in the editor to fill in the **Category**, **Display Name**, and **Subcategory** fields.
+#. When the Discussion component editor opens, follow the guidelines in the
+   editor to fill in the **Category**, the optional **Display Name**, and the 
+   **Subcategory** fields.
    
    .. image:: ../Images/DiscussionComponentEditor.png
-    :alt: Image of the discussion component editor
+    :alt: Image of the discussion component editor with a category of "Getting Graded" and a subcategory of "Answering More Than Once"
+
+   The value in the **Display Name** field identifies the discussion in the
+   course content. The values in the **Category** and **Subcategory** fields
+   appear in the list of discussion topics on the **Discussion** page. To
+   uniquely identify the discussion in your course, each **Category** /
+   **Subcategory** pair that you supply should be unique.
+
+   .. image:: ../Images/Discussion_category_subcategory.png
+    :alt: The list of discussions with the "Answering More Than Once" topic indented under "Getting Graded"
   
 #. Click **Save**.
 
@@ -83,7 +94,7 @@ components:
 In the **Discussion** tab at the top of the page, students can find the category
 and subcategory of the discussion in the left pane.
 
-.. image:: ../Images/DiscussionComponent_Forum.png
- :alt: Image of the discussion page from a student's point of view
+.. image:: ../Images/Discussion_category_subcategory.png
+ :alt: Image of the Discussion page from a student's point of view
 
 

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

@@ -1,8 +1,8 @@
 .. _Discussions:
 
-############################
-Discussions
-############################
+##################################
+Managing the Course Discussions
+##################################
 
 Discussions, or discussion forums, foster interaction among your students and
 between students and course staff. You can set up different topics to guide
@@ -47,16 +47,19 @@ levels of interaction.
   post as a whole.
  
 The dialog created by a post, its responses, and the comments on those
-repsonses is called a *thread*.
+responses is called a *thread*.
 
 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. 
+.. note:: 
+  The :ref:`Discussions for Students and Staff` chapter describes features that
+  are available to all discussion participants, and may be useful to students
+  who are new to online discussion forums. You can share the chapter with your
+  students by, for example, adding a "Never Used a Discussion Forum Before?"
+  post that includes the information you think will be most useful to them.
 
 .. _Organizing_discussions:
 
@@ -66,7 +69,8 @@ Set Up Discussions for Your Course
 
 Discussions in an edX course include both the specific topics that you add to
 course units as discussion components, and broader forums on course-wide areas
-of interest, such as Feedback, Troubleshooting, or Technical Help. You add both types of topics in Studio.
+of interest, such as "Feedback", "Troubleshooting", or "Technical Help". You
+add both types of topics in Studio.
 
 ============================================
 Add Units With a Discussion Component
@@ -76,7 +80,8 @@ Typically, all units are added during the design and creation of your course in
 Studio. To add a component to a unit, follow the instructions in :ref:`Working
 with Discussion Components`.
 
-This type of discussion is subject to the release date of the section that contains it. Students cannot contribute to these discussions until that date.
+This type of discussion is subject to the release date of the section that
+contains it. Students cannot contribute to these discussions until that date.
 
 =====================================
 Create Course-Wide Discussion Topics
@@ -152,7 +157,8 @@ these roles:
   banner. This role is often given to course team members who already have the
   Course Staff role.
 
-.. removed this clause from 1st sentence per JAAkana and MHoeber: , and, if the course is cohorted, see posts from all cohorts
+.. removed this clause from 1st sentence per JAAkana and MHoeber: , and, if the
+.. course is cohorted, see posts from all cohorts
 
 * Discussion community TAs have the same options for working with discussions
   as moderators. Posts made by community TAs are marked as "By: Community TA"
@@ -307,7 +313,8 @@ them available to students as a course handout file or on a defined page in
 your course. These guidelines can define your expectations and optionally
 introduce features of edX discussions.
 
-.. For a template that you can use to develop your own guidelines, see :ref:`Discussion Forum Guidelines`.
+.. For a template that you can use to develop your own guidelines, see
+.. :ref:`Discussion Forum Guidelines`.
 
 ========================================
 Develop a Positive Discussion Culture
@@ -409,7 +416,9 @@ that have been flagged in this way and edit or delete them as needed.
 Block Users
 ===============
 
-For a student who continues to misuse the course discussions, you can unenroll the student from the course. See :ref:`unenroll_student`. If the enrollment period for the course is over, the student cannot re-enroll.
+For a student who continues to misuse the course discussions, you can unenroll
+the student from the course. See :ref:`unenroll_student`. If the enrollment
+period for the course is over, the student cannot re-enroll.
 
 .. _Close_discussions:
 
@@ -507,4 +516,6 @@ reopen:
 
    .. image:: ../Images/Discussion_blackout_formatted.png
      :alt: Same policy value but with a line feed after each bracket and comma,
-         and an indent before each date
+         and an indent before each date
+
+.. For examples of email messages that you can send to let students know when the course discussions are closed (or open), see :ref:`Example Messages to Students`.

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

@@ -4,17 +4,19 @@
 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.
+community. If you have not previously participated in an online discussion
+forum, see the introductory :ref:`"anatomy"<Anatomy of edX Course Discussions>`
+section.
 
-Features of edX discussions that can make your participation more effective
-include ways to:
+This chapter also describes features of edX discussions that can make your
+participation more effective. These include ways to:
 
 * :ref:`Find Posts`
 
+* :ref:`Add a Post`
+
 * :ref:`Keep Up with New Activity`
 
 * :ref:`Follow Posts`
@@ -23,20 +25,86 @@ include ways to:
 
 * :ref:`Report Discussion Misuse`
 
+.. _Anatomy of edX Course Discussions:
+
+**********************************
+Anatomy of edX Course Discussions 
+**********************************
+
+====================================
+Posts, Responses, and Comments
+====================================
+
+::
+
+  Post: "Please introduce yourself."
+    - Reponse: "My name is Lee and I teach secondary school maths in Canberra,
+      Australia."
+    - Reponse: "Hello everyone, I am Sumei from Hong Kong, China."
+      - Comment: "Hi Sumei, I am taking this course in Hong Kong too. Maybe we
+        should make a study group!"
+      - Comment: "I'd like to join the Hong Kong study group too, I think it
+        will help me keep up with the homework."
+    - Response: "Hi from Johannesburg! I am taking the course to prepare for my
+      matric exams."
+
+This example shows the different ways that you can contribute to a discussion.
+The *post* initiates the conversation, *responses* are replies to the post, and
+*comments* expand on specific responses. Before you add a post, response, or
+comment, take a moment to consider which of these options best suits the
+contribution that you want to make. This helps keep course discussions
+organized and easy to follow.
+
+====================================
+Discussion Topics
+====================================
+
+Most edX courses include opportunities to discuss specific video lectures,
+reading assignments, questions, or other course content. Each of these content-
+specific discussion opportunities is called a *topic*. When these discussion
+topics are included in a course, they typically appear below the content they apply to.
+
+.. image:: /Images/Discussion_content_specific.png
+ :alt: A discussion topic that appears below a video in the course, identified by a "Show Discussion" link
+
+Most courses also include one or more topics for discussions about course-wide
+areas of interest, such as "Frequently Asked Questions" or "Troubleshooting".
+You access these topics on the **Discussion** page of the course.
+
+.. image:: /Images/Discussion_course_wide.png
+ :alt: Discussion topics are listed on the Discussion page when you click the drop-down list at the left side of the page
+
+When you visit the **Discussion** page, you can read and add to any of the
+discussion topics. 
+
+* Course-wide topics do not have other topics indented below them.
+
+* Content-specific topics are indented under an identifying category name. 
+
+Notice that while you can access content-specific topics both on the
+**Discussion** page and while you are navigating through course content on the
+**Courseware** page, you can only access the course-wide topics on the
+**Discussion** page.
+
+Before you add a post, look through the topics. When add your post to the most
+appropriate topic, others with the same interest can find, read, and respond to
+it more easily.
+
 .. _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.
+same subject that interests you, and then reading and contributing to that
+exchange instead of starting a new one, helps make the time that everyone
+spends with the course discussion more productive. 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
@@ -47,34 +115,158 @@ press Enter, the search tries to find:
   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.
+  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.
+**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.
+
+.. add something about endorsed responses(?)
+
+.. _Add a Post:
+
+************************************
+Add a Post, Response, or Comment
+************************************
+
+.. this section is likely to be more interesting and valuable when we add the discussion vs. question differentiation
+
+================================
+Add a Post
+================================
+
+To make sure that other students and the course team can find and respond to
+your posts, try to add your posts to the most appropriate topic.
+
+Add a Post to a Content-Specific Discussion Topic
+**************************************************
+
+#. Click **Courseware**.
+
+#. Open the part of the course that includes the discussion topic that you want
+   to add to.
+
+#. To read what others have already contributed to the conversation, click
+   **Show Discussion**.
+
+   You can scroll through the posts that have already been added: the title and
+   the first sentence or two of each post appear. To read the entire post, view
+   the responses to it, and see any comments, click **Expand discussion**.
+  
+4. To add a post, click **New Post**.
+
+.. image:: /Images/Discussion_content_specific_post.png
+  :alt: Adding a post about specific course content
+
+5. Enter a short, descriptive identifier for your post in the **Title** field.
+   The title is the part of your post that others see when they are browsing on
+   the **Discussion** page or scrolling through one of the content-specific
+   topics.
+
+#. Enter the complete text. Options for formatting the text and for adding
+   links or images are available: click the buttons above the text field.
+
+Add a Post to a Course-Wide Discussion Topic
+**************************************************
+
+You can also use this procedure to add a post to any of the content-specific
+discussion topics.
+
+#. Click the **Discussion** page.
+
+#. Click **New Post**.
+
+#. Select the most appropriate discussion topic for your post.
+
+.. image:: /Images/Discussion_course_wide_post.png
+  :alt: Selecting the topic for a new post on the Discussion page 
+
+4. Supply a short, descriptive **Title**. The title is the part of your post
+   that others see when they are browsing on the **Discussion** page or
+   scrolling through one of the content-specific topics.
+
+#. Enter the complete text. Options for formatting the text and for adding
+   links or images are available: click the buttons above the text field.
+
+===========================
+Add a Response or Comment
+===========================
+
+To participate in an ongoing discussion, you reply to the initial post by
+adding a response, or expand on a particular response by adding a comment.
+
+The same options for formatting the text and for adding links or images are
+available for responses and comments as for posts.
+
+Add a Response or Comment to a Content-Specific Discussion Topic
+****************************************************************
+
+#. Click **Courseware**.
+
+#. Open the part of the course with the discussion topic where you want to make
+   your contribution.
+
+#. Click **Show Discussion**.
+
+#. Scroll to the post where you want to add your thoughts.
+
+#. Click **Expand discussion**.
+
+#. Add a response or comment.   
+
+   To add a response to the post, click **Add A Response** below the post. When
+   your response is complete, click **Submit**.
+
+   To add a comment to a response, click in the **Add a comment** field below
+   the response. When your comment is complete, click **Submit**.
+
+Add a Response or Comment to a Course-Wide Discussion Topic
+************************************************************
+
+You can also use this procedure to add a response or comment to any of the
+content-specific discussion topics.
+
+#. Click the **Discussion** page.
+
+#. Find the post that you want to contribute to. To help you decide where to
+   add your thoughts, review the current responses and their comments.
+
+#. Add a response or comment.   
+
+   To add a response to the post, click **Add A Response** below the post. When
+   your response is complete, click **Submit**.
+
+   To add a comment to a response, click in the **Add a comment** field below
+   the response. When your comment is complete, click **Submit**.   
+
+.. images to come
 
 .. _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.
+The list of posts on the **Discussion** page 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".
 
@@ -88,12 +280,13 @@ distinguish them from exchanges that you have already read completely.
   :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`.
+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
@@ -101,9 +294,9 @@ 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
@@ -124,9 +317,9 @@ topic they apply to, click the drop-down Discussion list and select
 
 .. _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.
@@ -146,9 +339,9 @@ The number of votes that each post has received displays in the list of posts.
 
 .. _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

docs/en_us/data/source/internal_data_formats/discussion_data.rst

@@ -241,7 +241,7 @@ updated_at
 --------------------
 votes
 --------------------
-  Both ``CommentThread`` and ``Comment`` objects support voting. In the user interface, students can vote for posts (``CommentThread``s) and for responses, but not for the third-level comments made on responses. All ``Comment`` objects still have this attribute, even though there is no way to actually vote on the comment-level items in the UI. This attribute is a dictionary that has the following items inside:
+  Both ``CommentThread`` and ``Comment`` objects support voting. In the user interface, students can vote for posts (``CommentThread`` objects) and for responses, but not for the third-level comments made on responses. All ``Comment`` objects still have this attribute, even though there is no way to actually vote on the comment-level items in the UI. This attribute is a dictionary that has the following items inside:
 
   * up = list of User IDs that up-voted this comment or thread.
   * down = list of User IDs that down-voted this comment or thread (no longer used).