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

 .. _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:
 
@@ -508,3 +517,5 @@ 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
+
+.. 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/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).