New UI for discussions

docs/en_us/course_authors/source/change_log.rst

 ############
 Change Log
 ############
+       
+*****************
+September, 2014
+*****************
+
+.. list-table::
+   :widths: 10 70
+   :header-rows: 1
+
+   * - Date
+     - Change
+   * - 09/02/14
+     - Updated the :ref:`Discussions` and :ref:`Discussions for Students and
+       Staff` chapters to include information about choosing the type of post
+       and to reflect changes in the user interface.
+
 
 **************
 August, 2014

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

@@ -47,12 +47,14 @@ three hierarchical levels of interaction.
   post as a whole.
  
 The dialogue created by a post, its responses, and the comments on those
-responses is called a *thread*.
+responses is sometimes 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.
+course participants. Members of the course community, both staff and students,
+can be given permission to moderate or administer course discussions through a
+set of discussion administration roles. Discussion threads are saved as part of
+the course history.
 
 .. note:: 
   The :ref:`Discussions for Students and Staff` chapter describes features that
@@ -151,25 +153,27 @@ You can designate a team of people to help you run course discussions.
 Different options for working with discussions are available through
 these roles:
 
-* Discussion moderators can edit and delete messages at any level, review
+* *Discussion moderators* can edit and delete messages at any level, review
   messages flagged for misuse, close and reopen posts, pin posts, and endorse
   responses. Posts made by moderators are marked as "By: Staff" in the list of
   posts. Responses and comments made by moderators have a colored "Staff"
-  banner. This role is often given to course team members who already have the
-  Course Staff role.
+  identifier. 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
 
-* Discussion community TAs have the same options for working with discussions
+* *Discussion community TAs* have the same options for working with discussions
   as moderators. Posts made by community TAs are marked as "By: Community TA"
   in the list of posts on the **Discussion** page. Responses and comments made
-  by community TAs have a colored "Community TA" banner. This role is often
+  by community TAs have a colored "Community TA" identifier. This role is often
   given to students.
 
-* Discussion admins have the same options for working with discussions as
+.. put this comment in to make the formatting of this bulleted list consistent when output using the spinx template
+
+* *Discussion admins* have the same options for working with discussions as
   moderators, and their posts, responses, and comments have the same "Staff"
-  identifier. This role can be reserved for assignment to course team members
+  identifiers. This role can be reserved for assignment to course team members
   who have the Instructor role only: the discussion admins can then both
   moderate discussions and give other users these discussion management roles
   whenever necessary.
@@ -181,7 +185,7 @@ addresses or usernames.
   click **Membership** and then select **Course Staff** or **Instructor** from
   the drop-down list.
 
-* To get this information for any enrolled student, on the Instructor Dashboard
+* To get this information for an enrolled student, on the Instructor Dashboard
   click **Data Download**, then **Download profile information as a CSV**.
 
 To assign a role, you must be the course author or an Instructor (that is, you
@@ -272,28 +276,25 @@ discussion.
 * Pin a post. Pinning a post makes it appear at the top of the list of posts on
   the **Discussion** page. As a result, it is more likely that students will
   see and respond to pinned posts. You can write your own post and then pin it,
-  or pin a post by any author. Click **Pin Thread**.
+  or pin a post by any author. Select the "More" icon and then **Pin**.
 
     .. image:: ../Images/Pin_Discussion.png
      :alt: Image of the pin icon for discussion posts
 
 * Endorse a response. Endorsing a response indicates that it provides value to
-  the discussion. Click the **check** (or tick) mark icon that displays at
-  upper right of the response.
+  the discussion. Click the "check mark" (or tick mark) icon for the response.
 
     .. image:: ../Images/Endorse_Discussion.png
      :alt: Image of the Endorse button for discussion posts
 
-.. replace this image ^ when new one is available
-
 * Mark a question as answered. You use the same procedure to mark a response as
   the correct answer to a question as you do to endorse contributions to a
-  discussion. Click the **check** (or tick) mark icon for correct answers.
+  discussion: click the "check mark" (or tick mark) icon for correct answers.
 
 * Close a post. You can respond to a redundant post by (optionally) pasting in
   a link to the post that you prefer students to contribute to, and prevent
-  further interaction by closing the post. Click the **Close** button that
-  displays below the post to close it.
+  further interaction by closing the post. Select the "More" icon and then
+  **Close** to close it.
 
 * Provide post/response/comment guidelines. You can post information from the
   :ref:`overview<Overview_discussions>` in this chapter, or the :ref:`anatomy
@@ -395,12 +396,12 @@ In addition to these visual cues, filters can help you find questions and
 discussions that need review. Above the list of posts on the **Discussion**
 page, the **Show all** filter is selected by default. You can also select:
 
-* **Unanswered**, to list only questions that do not yet have any responses
-  marked as answers.
-
 * **Unread**, to list only the discussions and questions that you have not yet
   viewed.
 
+* **Unanswered**, to list only questions that do not yet have any responses
+  marked as answers.
+
 ==================
 Edit Messages
 ==================
@@ -413,8 +414,12 @@ text, images, or links.
 #. Log in to the site and then select the course on your **Current Courses**
    dashboard.
 
-#. Click the **Edit** button below the post or response, or click the pencil
-   icon for the comment.
+#. Open the **Discussion** page and then open the post with the content that
+   requires editing. You can select a single topic from the drop-down list of
+   discussion topics, apply a filter, or search to locate the post.
+
+#. For the post or for the response or comment that you want to edit, click the
+   "More" icon and then **Edit**.
 
 #. Remove the problematic portion of the message, or replace it with standard
    text such as "[REMOVED BY MODERATOR]".
@@ -433,34 +438,41 @@ language may need to be deleted, rather than edited.
 #. Log in to the site and then select the course on your **Current Courses**
    dashboard.
 
-#. Click the **Delete** button below the post or response or the "X" icon for
-   the comment.
+#. Open the **Discussion** page and then open the post with the content that
+   requires deletion. You can select a single topic from the drop-down list of
+   discussion topics, apply a filter, or search to locate the post.
+
+#. For the post or for the response or comment that you want to delete, click
+   the "More" icon and then **Delete**.
 
 #. Click **OK** to confirm the deletion.
 
 .. how to communicate with the poster?
 
-.. important:: If a message is threatening or indicates serious harmful intent, contact campus security at your institution. Report the incident before taking any other action.
+.. important:: If a message is threatening or indicates serious harmful 
+ intent, contact campus security at your institution. Report the incident
+ before taking any other action.
 
 ==================================
 Respond to Reports of Misuse
 ==================================
 
-Students can use the **Report Misuse** flag to indicate messages that they find
-inappropriate. Moderators, community TAs, and admins can check for messages
-that have been flagged in this way and edit or delete them as needed.
+Students have the option to report contributions that they find inappropriate.
+Moderators, community TAs, and admins can check for messages that have been
+flagged in this way and edit or delete them as needed.
 
 #. View the live version of your course and click **Discussion** at the top of
    the page.
 
 #. In the list of posts on the left side of the page, use the filter drop-down
-   (set to **Show all** by default) to select **Flagged**.
+   list (set to **Show all** by default) to select **Flagged**.
 
-#. Review each post listed as a flagged discussion. Posts and responses show a
-   flag and **Misuse Reported** in red font; comments show only a red flag.
+#. Review listed posts. A post is listed if it or any of its responses or
+   comments has been reported. The reported contribution includes a
+   **Reported** identifier.
 
-#. Edit or delete the post, response, or comment. Alternatively, to remove the
-   misuse flag from a message click **Misuse Reported** or the red flag icon.
+#. Edit or delete the post, response, or comment. Alternatively, remove the
+   flag: click the "More" icon and then **Unreport**.
 
 ===============
 Block Users
@@ -493,7 +505,9 @@ course units and all of the course-wide topics are affected.
   and Discussion Community TAs are not affected when you close the discussions
   for a course. Users with these roles can continue to add to discussions. 
 
-.. note:: To assure that your students understand why they cannot add to  discussions, you can add the dates that discussions are closed to the **Course Info** page and post them to a General discussion.
+.. note:: To assure that your students understand why they cannot add to 
+  discussions, you can add the dates that discussions are closed to the
+  **Course Info** page and post them to a General discussion.
 
 =====================================
 Start-End Date Format Specification

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

@@ -19,11 +19,7 @@ participation more effective. These include ways to:
 
 * :ref:`Keep Up with New Activity`
 
-* :ref:`Follow Posts`
-
-* :ref:`Vote for Posts or Responses`
-
-* :ref:`Report Discussion Misuse`
+* :ref:`React to Contributions`
 
 .. _Anatomy of edX Course Discussions:
 
@@ -60,19 +56,23 @@ 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.
+reading assignments, homework problems, 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
+ :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 course-wide discussions, such
 as "Frequently Asked Questions" and "Troubleshooting". You access these topics
-on the **Discussion** page of the course.
+on the **Discussion** page of the course: click the **All Discussions**
+drop-down.
 
 .. 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
+ :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. 
@@ -81,9 +81,9 @@ discussion topics.
 
 * 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
+Notice that you can access content-specific topics both on the **Discussion**
+page and also while you are navigating through course content on the
+**Courseware** page. However, you can only access the course-wide topics on the
 **Discussion** page.
 
 Before you add a post, look through the topics. When you add your post to the
@@ -121,11 +121,12 @@ open-ended conversation (a discussion).
 Find Posts
 ******************************
 
-Finding out whether someone else has already started a conversation about the
-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.
+Finding out whether someone else has already asked the same question or
+initiated a conversation about the 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
@@ -159,7 +160,8 @@ down list. (**All Discussions** is selected by default.) Only posts about the
 topic you select appear in the list of posts.
 
 .. image:: ../Images/Discussion_filters.png
- :alt: The list of posts with callouts to identify the top filter to select one topic and the filter below it to select by state 
+ :alt: The list of posts with callouts to identify the top filter to select 
+       one topic and the filter below it to select by state 
 
 =======================================
 Review Only Unread or Unanswered Posts
@@ -185,7 +187,8 @@ Add a Post
 ================================
 
 To make sure that other students and the course team can find and respond to
-your post, try to select the correct type for your post: either question or discussion.
+your post, try to select the correct type for your post: either question or
+discussion.
 
 Add a Post to a Content-Specific Discussion Topic
 **************************************************
@@ -199,7 +202,7 @@ Add a Post to a Content-Specific Discussion Topic
    **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 first sentence or two of each post appear. To read an entire post, view
    the responses to it, and see any comments, click **Expand discussion**.
   
 4. To add a post, click **New Post**.
@@ -264,13 +267,16 @@ Add a Response or Comment to a Content-Specific Discussion Topic
 #. Scroll to the post where you want to add your thoughts.
 
 #. Click **Expand discussion**.
+   
+  .. image:: /Images/Discussion_expand.png
+    :alt: The **Expand discussion** link under a post
 
-#. Add a response or comment.   
+6. 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 response to the post, click **Add A Response**. When your response
+   is complete, click **Submit**.
 
-   To add a comment to a response, click in the **Add a comment** field below
+ - 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
@@ -284,15 +290,17 @@ content-specific discussion topics.
 #. 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.   
+#. 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 response to the post, click **Add A Response**. 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**.   
+  .. image:: /Images/Discussion_add_response.png
+    :alt: The **Add A Response** button located between a post and its 
+          responses 
 
-.. images to come
+ - To add a comment to a response, click in the **Add a comment** field below
+   the response. When your comment is complete, click **Submit**.   
 
 .. _Keep Up with New Activity:
 
@@ -318,16 +326,21 @@ completely.
   background.
 
  .. image:: ../Images/Discussion_colorcoding.png
-  :alt: The list of posts with posts showing differently colored backgrounds and callout images
+  :alt: The list of posts with posts showing differently colored backgrounds 
+        and callout images
 
 The total number of contributions in the exchange (the post and its responses
 and comments) appears in each callout image. To see the number of contributions
-that you haven't read yet, move your cursor to hover over the callout image.
+that you haven't read yet, move your cursor over the callout image.
 
-These color-coded callout images 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 callouts. See :ref:`Vote for Posts or Responses`.
+.. image:: ../Images/Discussion_mouseover.png
+ :alt: A post with 4 contributions total and a popup that shows only two are 
+       unread 
+
+The color-coded callout images 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 callouts. See :ref:`Vote for Posts or Responses`.
 
 ==============================
 Receive Daily Digests
@@ -337,37 +350,52 @@ 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:
+
+.. _React to Contributions:
 
 ************************************
-Follow Posts
+Provide Feedback on Contributions
 ************************************
 
-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.
+As you read the contributions that other students and staff make to discussion
+topics, you can provide feedback without writing a complete response or
+comment. You can:
 
-.. image:: ../Images/Discussion_follow.png
- :alt: A post with the Follow icon circled
+* :ref:`Vote for posts and responses<Vote for Posts or Responses>` to provide
+  positive feedback.
 
-Each post that you follow appears with a "Following" badge in the list of
-posts.
+* :ref:`Follow posts<Follow Posts>` so that you can check back in on
+  interesting conversations and questions easily.
 
-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**.
+* :ref:`Answer questions, and mark your questions as answered<Answer
+  Questions>`.
 
-.. image:: ../Images/Discussion_filterfollowing.png
- :alt: The list of posts with the "Posts I'm Following" filter selected. Every post shows the following badge.
+* :ref:`Report a contribution<Report Discussion Misuse>` that is inappropriate
+  to the course staff.
+
+To select a feedback option, you use the icons at the top right of each post,
+response, or comment. When you move your cursor over these icons a label
+appears.
+
+.. image:: ../Images/Discussion_options_mouseover.png
+ :alt: The icons at top right of a post, shown before the cursor is 
+      placed over each one and with the Vote, Follow, and More labels
+
+When you click the "More" icon, a menu of the options that currently apply
+appears.
+
+.. image:: ../Images/Discussion_More_menu.png
+ :alt: The More icon expanded to show a menu with one option and a menu with 
+       three options
 
 .. _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.
+post or response and click the "Vote" icon at top right.
 
 .. image:: ../Images/Discussion_vote.png
  :alt: A post with the Vote icon circled
@@ -377,45 +405,70 @@ 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
+ :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.)
 
+.. _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 "Follow" icon.
+
+.. image:: ../Images/Discussion_follow.png
+ :alt: A post with the Follow icon circled
+
+Each post that you follow appears with a "Following" indicator 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 in the list shows the following indicator.
+
 .. _Answer Questions:
 
-************************************************************
+============================================================
 Answer Questions and Mark Questions as Answered 
-************************************************************
+============================================================
 
-Anyone in a course can answer questions. Just add a response to the post with
-your answer.
+Anyone in a course can answer questions. Just add a response to the question
+post with your answer.
 
-The person who posted the question and staff members can mark responses as
-correct: click the **check** (or tick mark) icon that appears at upper right of
+The person who posted the question (and staff members) can mark responses as
+correct: click the "Mark as Answer" icon that appears at upper right of
 the response.
 
 .. image:: ../Images/Discussion_answer_question.png
- :alt: 
+ :alt: A question and a response, with the Mark as Answer icon circled
 
 After at least one response is marked as the answer, a check or tick mark image
 replaces the question mark image for the post in the list on the **Discussion**
 page.
 
 .. image:: ../Images/Discussion_answers_in_list.png
- :alt: The list of posts with images identifying unanswered and answered questions and discussions 
+ :alt: The list of posts with images identifying unanswered and answered
+     questions and discussions
 
 .. _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.
+review: view the contribution, click the "More" icon, and then click
+**Report**.
 
 .. 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
+ :alt: A post and a response with the "Report" link 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/data/source/internal_data_formats/discussion_data.rst

@@ -4,21 +4,34 @@
 Discussion Forums Data
 ######################
 
-EdX discussion data is stored as collections of JSON documents in a MongoDB database. MongoDB is a document-oriented, NoSQL database system. Documentation can be found at the mongodb_ web site.
+EdX discussion data is stored as collections of JSON documents in a MongoDB
+database. MongoDB is a document-oriented, NoSQL database system. Documentation
+can be found at the mongodb_ web site.
 
 ..  _mongodb: http://docs.mongodb.org/manual/
 
-In the data package, discussion data is delivered in a .mongo file, identified by organization and course, in this format: edX-*organization*-*course*-*source*.mongo. 
+In the data package, discussion data is delivered in a .mongo file, identified
+by organization and course, in this format:
+edX-*organization*-*course*-*source*.mongo.
 
-The primary collection that holds all of the discussion posts written by users is "contents". Two different types of objects are stored, representing the three levels of interactions that users can have in a discussion. 
+The primary collection that holds all of the discussion posts written by users
+is "contents". Two different types of objects are stored, representing the
+three levels of interactions that users can have in a discussion.
 
-* A ``CommentThread`` represents the first level of interaction: a post that opens a new thread, often a student question of some sort. 
+* A ``CommentThread`` represents the first level of interaction: a post that
+  opens a new thread, often a student question of some sort.
 
-* A ``Comment`` represents both the second and third levels of interaction: a response made directly to the conversation started by a ``CommentThread`` is a ``Comment``. Any further contributions made to a specific response are also in ``Comment`` objects.
+* A ``Comment`` represents both the second and third levels of interaction: a
+  response made directly to the conversation started by a ``CommentThread`` is
+  a ``Comment``. Any further contributions made to a specific response are also
+  in ``Comment`` objects.
 
-A sample of the field/value pairs that are in the mongo file, and descriptions of the attributes that these two types of objects share and that are specific to each type, follow.
+A sample of the field/value pairs that are in the mongo file, and descriptions
+of the attributes that these two types of objects share and that are specific
+to each type, follow.
 
-In addition to these collections, events are also emitted to track specific user activities. See :ref:`forum_events`.
+In addition to these collections, events are also emitted to track specific
+user activities. See :ref:`forum_events`.
 
 *********
 Samples
@@ -36,68 +49,72 @@ machine-readable format that can be difficult to read at a glance.
 
 .. code-block:: json
 
- { "_id" : { "$oid" : "50f1dd4ae05f6d2600000001" }, "_type" : "CommentThread", "anonymous" : 
- false, "anonymous_to_peers" : false, "at_position_list" : [], "author_id" : "NNNNNNN", 
- "author_username" : "AAAAAAAAAA", "body" : "Welcome to the edX101 forum!\n\nThis forum will 
- be regularly monitored by edX. Please post your questions and comments here. When asking a 
- question, don't forget to search the forum to check whether your question has already been 
- answered.\n\n", "closed" : false, "comment_count" : 0, "commentable_id" : "i4x-edX-edX101-
- course-How_to_Create_an_edX_Course", "course_id" : "edX/edX101/How_to_Create_an_edX_Course", 
- "created_at" : { "$date" : 1358028106904 }, "last_activity_at" : { "$date" : 1358134464424 }, 
- "tags_array" : [], "title" : "Welcome to the edX101 forum!", "updated_at" : { "$date" : 
- 1358134453862 }, "votes" : { "count" : 1, "down" : [], "down_count" : 0, "point" : 1, "up" : 
- [ "48" ], "up_count" : 1 } }
+ { "_id" : { "$oid" : "50f1dd4ae05f6d2600000001" }, "_type" : "CommentThread",
+ "anonymous" :false, "anonymous_to_peers" : false, "at_position_list" : [],
+ "author_id" : "NNNNNNN","author_username" : "AAAAAAAAAA", "body" : "Welcome to
+ the edX101 forum!\n\nThis forum willbe regularly monitored by edX. Please post
+ your questions and comments here. When asking aquestion, don't forget to
+ search the forum to check whether your question has already
+ beenanswered.\n\n", "closed" : false, "comment_count" : 0, "commentable_id" :
+ "i4x-edX-edX101-course-How_to_Create_an_edX_Course", "course_id" :
+ "edX/edX101/How_to_Create_an_edX_Course","created_at" : { "$date" :
+ 1358028106904 }, "last_activity_at" : { "$date" : 1358134464424 },"tags_array"
+ : [], "thread_type": "discussion", "title" : "Welcome to the edX101 forum!",
+ "updated_at" : { "$date" :1358134453862 }, "votes" : { "count" : 1, "down" :
+ [], "down_count" : 0, "point" : 1, "up" :[ "48" ], "up_count" : 1 } }
 
 If you use a JSON formatter to "pretty print" this document, a version that is
 more readable is produced.
 
 .. code-block:: json
 
-  {
-    "_id": {
-      "$oid": "50f1dd4ae05f6d2600000001"
-    },
-    "_type": "CommentThread",
-    "anonymous": false,
-    "anonymous_to_peers": false,
-    "at_position_list": [
-    
+ {
+  "_id": {
+    "$oid": "50f1dd4ae05f6d2600000001"
+  },
+  "_type": "CommentThread",
+  "anonymous": false,
+  "anonymous_to_peers": false,
+  "at_position_list": [
+ 
+  ],
+  "author_id": "NNNNNNN",
+  "author_username": "AAAAAAAAAA",
+  "body": "Welcome to the edX101 forum!\n\nThis forum will be regularly 
+  monitored by edX. Please post your questions and comments here. When 
+  asking a question, don't forget to search the forum to check whether 
+  your question has already been answered.\n\n",
+  "closed": false,
+  "comment_count": 0,
+  "commentable_id": "i4x-edX-edX101-course-How_to_Create_an_edX_Course",
+  "course_id": "edX\/edX101\/How_to_Create_an_edX_Course",
+  "created_at": {
+    "$date": 1358028106904
+  },
+  "last_activity_at": {
+    "$date": 1358134464424
+  },
+  "tags_array": [
+ 
+  ],
+  "thread_type": "discussion",
+  "title": "Welcome to the edX101 forum!",
+  "updated_at": {
+    "$date": 1358134453862
+  },
+  "votes": {
+    "count": 1,
+    "down": [
+ 
     ],
-    "author_id": "NNNNNNN",
-    "author_username": "AAAAAAAAAA",
-    "body": "Welcome to the edX101 forum!\n\nThis forum will be regularly monitored by edX. Please 
-    post your questions and comments here. When asking a question, don't forget to search the  
-    forum to check whether your question has already been answered.\n\n",
-    "closed": false,
-    "comment_count": 0,
-    "commentable_id": "i4x-edX-edX101-course-How_to_Create_an_edX_Course",
-    "course_id": "edX\/edX101\/How_to_Create_an_edX_Course",
-    "created_at": {
-      "$date": 1358028106904
-    },
-    "last_activity_at": {
-      "$date": 1358134464424
-    },
-    "tags_array": [
-    
+    "down_count": 0,
+    "point": 1,
+    "up": [
+      "48"
     ],
-    "title": "Welcome to the edX101 forum!",
-    "updated_at": {
-      "$date": 1358134453862
-    },
-    "votes": {
-      "count": 1,
-      "down": [
-      
-      ],
-      "down_count": 0,
-      "point": 1,
-      "up": [
-        "48"
-      ],
-      "up_count": 1
-    }
+    "up_count": 1
   }
+}
 
 ----------------------------------------
 Comment Document Example
@@ -105,71 +122,82 @@ Comment Document Example
 
 .. code-block:: json
 
- { "_id" : { "$oid" : "52e54fdd801eb74c33000070" }, "votes" : { "up" : [], "down" : [], 
- "up_count" : 0, "down_count" : 0, "count" : 0, "point" : 0 }, "visible" : true, 
- "abuse_flaggers" : [], "historical_abuse_flaggers" : [], "parent_ids" : [], "at_position_list" : 
- [], "body" : "I'm hoping this Demonstration course will help me figure out how to take the 
- course I registered for. I am just auditing the course, but I want to benefit from it as much 
- as possible, as I am extremely interested in it.\n", "course_id" : "edX/DemoX/Demo_Course", 
- "_type" : "Comment", "endorsed" : false, "anonymous" : false, "anonymous_to_peers" : false, 
- "author_id" : "NNNNNNN", "comment_thread_id" : { "$oid" : "52e4e880c0df1fa59600004d" }, 
- "author_username" : "AAAAAAAAAA", "sk" : "52e54fdd801eb74c33000070", "updated_at" : 
- { "$date" : 1390759901966 }, "created_at" : { "$date" : 1390759901966 } }
+ { "_id" : { "$oid" : "52e54fdd801eb74c33000070" }, "votes" : { "up" : [],
+ "down" : [], "up_count" : 0, "down_count" : 0, "count" : 0, "point" : 0 },
+ "visible" : true, "abuse_flaggers" : [], "historical_abuse_flaggers" : [],
+ "parent_ids" : [], "at_position_list" : [], "body" : "I'm hoping this
+ Demonstration course will help me figure out how to take the course I
+ registered for. I am just auditing the course, but I want to benefit from it
+ as much as possible, as I am extremely interested in it.\n", "course_id" :
+ "edX/DemoX/Demo_Course", "_type" : "Comment", "endorsed" : true, "endorsement"
+ : { "user_id" : "9", "time" : ISODate("2014-08-29T15:11:49.442Z") },
+ "anonymous" : false, "anonymous_to_peers" : false, "author_id" : "NNNNNNN",
+ "comment_thread_id" : { "$oid" : "52e4e880c0df1fa59600004d" },
+ "author_username" : "AAAAAAAAAA", "sk" : "52e54fdd801eb74c33000070",
+ updated_at" : { "$date" : 1390759901966 }, "created_at" : { "$date" :
+ 1390759901966 } }
 
 When pretty printed, this comment looks like this:
 
 .. code-block:: json
 
-  {
-    "_id": {
-      "$oid": "52e54fdd801eb74c33000070"
-    },
-    "votes": {
-      "up": [
-      
-      ],
-      "down": [
-      
-      ],
-      "up_count": 0,
-      "down_count": 0,
-      "count": 0,
-      "point": 0
-    },
-    "visible": true,
-    "abuse_flaggers": [
-    
-    ],
-    "historical_abuse_flaggers": [
-    
+ {
+  "_id": {
+    "$oid": "52e54fdd801eb74c33000070"
+  },
+  "votes": {
+    "up": [
+ 
     ],
-    "parent_ids": [
-    
+    "down": [
+ 
     ],
-    "at_position_list": [
-    
-    ],
-    "body": "I'm hoping this Demonstration course will help me figure out how to take the 
-    course I registered for. I am just auditing the course, but I want to benefit from it 
-    as much as possible, as I am extremely interested in it.\n",
-    "course_id": "edX\/DemoX\/Demo_Course",
-    "_type": "Comment",
-    "endorsed": false,
-    "anonymous": false,
-    "anonymous_to_peers": false,
-    "author_id": "NNNNNNN",
-    "comment_thread_id": {
-      "$oid": "52e4e880c0df1fa59600004d"
-    },
-    "author_username": "AAAAAAAAAA",
-    "sk": "52e54fdd801eb74c33000070",
-    "updated_at": {
-      "$date": 1390759901966
-    },
-    "created_at": {
-      "$date": 1390759901966
+    "up_count": 0,
+    "down_count": 0,
+    "count": 0,
+    "point": 0
+  },
+  "visible": true,
+  "abuse_flaggers": [
+ 
+  ],
+  "historical_abuse_flaggers": [
+ 
+  ],
+  "parent_ids": [
+ 
+  ],
+  "at_position_list": [
+ 
+  ],
+  "body": "I'm hoping this Demonstration course will help me figure out how 
+  to take the course I registered for. I am just auditing the course, but I 
+  want to benefit from it as much as possible, as I am extremely interested 
+  in it.\n",
+  "course_id": "edX\/DemoX\/Demo_Course",
+  "_type": "Comment",
+  "endorsed": true,
+  "endorsement": {
+    "user_id": "9",
+    "time": {
+      "$date": 1390759911966
     }
   }
+  "anonymous": false,
+  "anonymous_to_peers": false,
+  "author_id": "NNNNNNN",
+  "comment_thread_id": {
+    "$oid": "52e4e880c0df1fa59600004d"
+  },
+  "author_username": "AAAAAAAAAA",
+  "sk": "52e54fdd801eb74c33000070",
+  "updated_at": {
+    "$date": 1390759901966
+  },
+  "created_at": {
+    "$date": 1390759901966
+  }
+}
 
 *****************
 Shared Fields
@@ -305,7 +333,7 @@ thread_type
 --------------------
   Identifies the type of post as a "question" or "discussion".  
 
-  **History**: Added 12 Aug 2014.
+  **History**: Added 2 Sep 2014.
 
 ********************
 Comment Fields
@@ -350,7 +378,7 @@ endorsement
   response to a post was endorsed and the numeric user ID (from
   ``auth_user.id``) of the person who endorsed it.
 
-  **History**: Added 12 Aug 2014.
+  **History**: Added 2 Sep 2014.
 
 --------------------
 comment_thread_id