Merge pull request #5327 from edx/ahodges/doc/cohorts

Ahodges/doc/cohorts

docs/en_us/course_authors/source/cohorts/cohort_config.rst

@@ -0,0 +1,312 @@
+.. _Enabling and Configuring Cohorts:
+
+############################################
+Enabling and Configuring the Cohort Feature
+############################################
+
+To support discussions that are divided by cohort, you select a strategy
+for assigning your students to cohort groups: automated assignment, manual
+assignment, or a hybrid approach. See :ref:`Options for Assigning Students to
+Cohorts`. You also decide whether to change any of the course-wide discussion
+topics so that they are divided by cohort instead of unified for all students. 
+
+After you select a strategy, you complete these configuration steps (as
+applicable):
+
+#. :ref:`Enable the cohort feature<Enable Cohorts>`.
+
+#. Based on the strategy you select for assigning students to cohort groups:
+   
+  * :ref:`Define the auto cohort groups<Define Auto Cohort Groups>`.
+
+  * :ref:`Define the manual cohort groups<Define the Manual Cohort Groups>` and
+    then :ref:`assign students<Assign Students to Cohort Groups
+    Manually>` to them.
+
+  * Do both. 
+
+3. Identify the :ref:`course-wide discussion topics<Identifying Private
+   CourseWide Discussion Topics>` that you want to be divided by cohort. This
+   procedure is optional.
+
+You complete these procedures in Studio and on the Instructor Dashboard. For an
+optimal student experience, configuration of the cohort feature should be as
+complete as possible prior to the start date of your course. 
+
+.. If you need to make changes to the way you have configured the cohort feature while your course is running, please see :ref:`%%`.
+
+.. _Enable Cohorts:
+
+********************************
+Enabling the Cohort Feature
+********************************
+
+#. Open the course in Studio. 
+
+#. Select **Settings**, then **Advanced Settings**.
+
+#. In the **Cohort Configuration** field, place your cursor between the
+   supplied pair of braces.
+
+#. Type ``"cohorted": true``. 
+
+#. Click **Save Changes**. Studio reformats the name:value pair you just
+   entered to indent it on a new line.
+   
+ .. image:: ../Images/Enable_cohorts.png
+  :alt: Cohort Configuration dictionary field with the cohorted key defined 
+        as true
+
+You can then :ref:`implement the automated assignment strategy<Implementing the
+Automated Assignment Strategy>`, :ref:`implement the manual assignment
+strategy<Implementing the Manual Assignment Strategy>`, or both.
+
+.. _Implementing the Automated Assignment Strategy:
+
+***************************************************
+Implementing the Automated Assignment Strategy
+***************************************************
+
+To implement automated assignment of students to cohort groups you define the
+auto cohort groups in the **Cohort Configuration** advanced setting field.
+
+You complete this procedure if you are using either the automated or hybrid
+assignment strategy for your course. For more information, see :ref:`All
+Automated Assignment` or :ref:`Hybrid Assignment`.
+
+.. _Define Auto Cohort Groups:
+
+============================================
+Define the Auto Cohort Groups
+============================================
+
+.. note:: Students can see the name of the cohort group they are assigned to. 
+ The message "This post is visible only to {cohort name}" appears with each
+ post in discussion topics that are divided by cohort. See :ref:`Read the
+ Cohort Indicator in Posts`.
+
+.. note: You cannot delete cohort groups or change their names. If you need to make changes to the way you have configured the cohort feature while your course is running, please see :ref:`%%`.
+
+#. Open the course in Studio. 
+
+#. Select **Settings**, then **Advanced Settings**.
+
+#. In the **Cohort Configuration** field, place your cursor after the opening
+   brace character (``{``) and press Enter.
+
+#. On the new line, you define the ``"auto_cohort_groups":`` policy key,
+   followed by one or more cohort group names enclosed by square brackets (``[
+   ]``). You can define a set of auto cohort groups or just one.
+
+   To define a set of groups, you type each group name on a new line, enclose
+   it within quotation marks (``" "``), and separate the quoted name values
+   with commas. For example:
+   
+ .. code:: 
+
+   "auto_cohort_groups": [
+       "Example Group Name A",
+       "Example Group Name B",
+       "Example Group Name C"
+   ]
+   
+.. comment is here only to allow indented formatting of next line
+
+  You can also define only a single auto cohort group. Type
+   ``"auto_cohort_groups": ["Example Group Name"]`` and then press Enter again.
+
+5. Type a comma after the closing square bracket character (``],``). You must
+   include a comma to separate each of the policy keys that you define.
+   
+#. Click **Save Changes**. Studio resequences and reformats your entry. Scroll
+   back to the **Cohort Configuration** field to verify that your entry was
+   saved as you expect. Entries that do not contain all of the required
+   punctuation characters revert to the previous value when you save, and no
+   warning is presented.
+
+ .. image:: ../Images/Multiple_auto_cohort_groups.png
+  :alt: Cohort Configuration dictionary field with the auto_cohort_groups key 
+        with three values
+
+.. spacer line
+
+ .. image:: ../Images/Single_auto_cohort_group.png
+  :alt: Cohort Configuration dictionary field with the auto_cohort_groups key 
+        with one value
+
+Any student who is not already assigned to a cohort group will be randomly
+assigned to one of the auto cohort groups when she visits any of the course
+discussion topics.
+
+For a report that includes the cohort group assignment for every enrolled
+student, review the student profile information for your course. See
+:ref:`View and download student data`.
+
+.. _Implementing the Manual Assignment Strategy:
+
+***************************************************
+Implementing the Manual Assignment Strategy
+***************************************************
+
+To implement manual assignment of students to cohort groups, you define the
+manual cohort groups and then assign students to them. 
+
+You complete these procedures if you are using either the manual or hybrid
+assignment strategy for your course. For more information, see :ref:`All Manual
+Assignment` or :ref:`Hybrid Assignment`.
+
+You must :ref:`enable the cohort feature<Enable Cohorts>` for your course
+before you can complete these procedures.
+
+.. note: You cannot delete cohort groups or change their names. If you need to make changes to the way you have configured the cohort feature while your course is running, please see :ref:`%%`.
+
+
+.. _Define the Manual Cohort Groups:
+
+==========================================
+Define the Manual Cohort Groups
+==========================================
+
+.. note:: Students can see the name of the cohort group they are assigned to. 
+ The message "This post is visible only to {cohort name}" appears with each
+ post in discussion topics that are divided by cohort. See :ref:`Read the
+ Cohort Indicator in Posts`.
+
+#. View the live version of your course. For example, in Studio click **View
+   Live**.
+
+#. Click **Instructor**, then click **Membership**. 
+
+#. Scroll to the **Cohort Management** section at the bottom.
+
+#. Click **Add Cohort Group**.
+
+#. Supply a name for the group, and then click **Save** below the **New Cohort
+   Name** field.
+
+.. _Assign Students to Cohort Groups Manually:
+
+==========================================
+Assign Students to Cohort Groups Manually
+==========================================
+
+.. note:: Manual assignments should be as complete as possible before your 
+ course starts. If student enrollment continues after your course starts, you
+ should continue to assign new students to cohort groups. To review the cohort
+ group assignments of every enrolled student, generate the student profile
+ information report for your course. See :ref:`View and download student data`.
+
+#. View the live version of your course. For example, in Studio click **View
+   Live**.
+
+#. Click **Instructor**, then click **Membership**. 
+
+#. Scroll to the **Cohort Management** section at the bottom.
+
+#. Select a cohort group from the drop down list.
+
+#. In the **Add students** field, enter the username or email address of a
+   single student, or enter multiple names or addresses separated by commas or
+   new lines. You can copy data from a CSV file of email addresses and paste it
+   into this field.
+
+#. Click **Add Students**. The students are assigned to the selected manual
+   cohort group. A message appears to indicate the number of students who were
+   added to the cohort group. Because students can belong to only one cohort
+   group, the message also indicates the number of students whose assignment to
+   another cohort group was changed by this procedure.
+
+.. _Identifying Private CourseWide Discussion Topics:
+
+*****************************************************************
+Configuring Course-Wide Discussion Topics To Be Divided
+*****************************************************************
+
+When you enable the cohort feature for a course, all of the course-wide
+discussion topics provide unified access to posts for all students. You can
+configure one or more of the course-wide topics to be divided by cohort
+instead.
+
+.. note:: The content-specific discussion topics in the course, which are 
+ added to units as discussion components, are always divided by cohort.
+
+For more information about content-specific and course-wide discussion topics,
+see :ref:`Organizing_discussions`.
+
+Before you configure course-wide discussion topics to be divided by cohort, you
+add the topics in Studio. See :ref:`Create CourseWide Discussion Topics`. In
+the example given for creating course-wide discussion topics, a single topic,
+Course Q&A, is added to the system-supplied General topic. The steps in the
+following procedure expand on that example: you have now decided to enable the
+cohort feature for your course. The posts that you intend to make to the Course
+Q&A and General topics, and the subjects you expect students to explore there,
+are appropriate for a unified student audience. However, you also want to give
+students some course-wide topics that are divided by cohort. You define two
+more course-wide discussion topics, Announcements and Brainstorming.
+
+You also decide to apply a naming convention so that students will know 
+the audience for their posts before they add them. See :ref:`Apply Naming
+Conventions to Discussion Topics`. 
+
+.. image:: ../Images/Discussion_Add_cohort_topics.png
+ :alt: Discussion Topic Mapping field with four course-wide discussion topics 
+       defined
+
+.. _Configure CourseWide Discussion Topics as Private:
+
+======================================================
+Identify Divided Course-Wide Discussion Topics
+======================================================
+
+In the steps that follow, you configure two topics so that they are divided
+by cohort. On the Studio **Advanced Settings** page, the two topics appear as follows in the **Discussion Topic Mapping** field:
+
+.. code::
+
+      "Brainstorming (private)": {
+          "id": "i4x-edX-Open-edx_demo_course_brainstorming"
+      },
+      "Announcements (private)": {
+          "id": "i4x-edX-Open-edx_demo_course_announcements"
+      }
+
+#. Open the course in Studio. 
+
+#. Select **Settings**, then **Advanced Settings**.
+
+#. In the **Cohort Configuration** field, place your cursor after the opening
+   brace character (``{``) and press Enter.
+
+#. On the new line, you define the ``"cohorted_discussions":`` policy key,
+   followed by one or more course-wide discussion topic IDs enclosed by
+   square brackets (``[ ]``). You can define a set of discussion topics or just
+   one.
+
+   To define a set of topics, you type the value of the "id" for each
+   discussion topic on a new line, enclose it within quotation marks (``" "``),
+   and separate the quoted "id" values with commas. For example:
+
+ .. code:: 
+
+   "cohorted_discussions": [
+       "i4x-edX-Open-edx_demo_course_announcements",
+       "i4x-edX-Open-edx_demo_course_brainstorming"
+   ]
+   
+.. this comment is here only to force allow indented formatting of next line
+
+  To specify a single discussion topic, type ``"cohorted_discussions": ["i4x-
+  test_doc-SB101-course-2014_Jan_announcements"]`` and then press Enter again.
+   
+5. Type a comma after the closing square bracket character (``],``). You must
+   include a comma to separate each of the policy keys that you define.
+   
+#. Click **Save Changes**. Studio resequences and reformats your entry. Scroll
+   back to the **Cohort Configuration** field to verify that your entry was
+   saved as you expect. Entries that do not contain all of the required
+   punctuation characters revert to the previous value when you save, and no
+   warning is presented.
+
+ .. image:: ../Images/Configure_cohort_topic.png
+  :alt: Cohort Configuration dictionary field with the cohorted_discussions key
+        defined

docs/en_us/course_authors/source/cohorts/cohorts_discussions.rst

@@ -0,0 +1,99 @@
+.. _Moderating Discussions for Cohorts:
+
+##########################################################
+Managing Discussions in a Course with Student Cohorts
+##########################################################
+
+The experience that students have in the course discussions is different in
+courses that do, and do not, enable the cohort feature. Additional features are
+also available to the staff members and community TAs who moderate the course
+discussions. This section describes how students and staff can :ref:`find out
+who can read a post<Finding Out Who Can See a Post>`.
+
+.. to come in a separate PR: a better introduction, info on how a moderator can post into one cohort or all cohorts, how students see posts in a course with cohorts, more
+
+.. _Finding Out Who Can See a Post:
+
+********************************
+Finding Out Who Can Read a Post
+********************************
+
+In a course with the cohort feature enabled, all posts include a cohort
+indicator above the title. This indicator appears after a student or staff
+member adds each post. Other than choosing the cohort group names carefully
+when you add them, no configuration is necessary to include this identifier.
+You can share the information in the :ref:`Read the Cohort Indicator in Posts`
+section with your students.
+
+For students to see who will be able to read their posts before they add them,
+you can name the discussion topics so that they identify who will be able to
+see posts. See :ref:`Apply Naming Conventions to Discussion Topics`.
+
+.. _Read the Cohort Indicator in Posts:
+
+==================================
+Read the Cohort Indicator in Posts
+==================================
+
+Every post includes a sentence that identifies whether everyone can see and
+contribute to it, or only the members of a cohort within the course.
+
+.. image:: ../Images/post_visible_all.png
+ :alt: A discussion topic post with "This post is visible to everyone" above 
+       the title
+
+.. image:: ../Images/post_visible_cohort.png
+ :alt: A discussion topic post with "This post is visible to" and a cohort name
+       above the title
+
+.. image:: ../Images/post_visible_default.png
+ :alt: A discussion topic post with "This post is visible to Default Group" 
+       above the title
+
+You see this identifier after you add your post. The responses and comments
+that others add to a post are visible to the same group of people as the
+post itself.
+
+.. _Apply Naming Conventions to Discussion Topics:
+
+=========================================================
+Apply Naming Conventions to Discussion Topics
+=========================================================
+
+All of the content-specific discussion topics that you add to units in Studio
+are divided by cohort. However, course-wide topics can either be divided by
+cohort or remain unified (all students can read and react to all posts).
+
+Optionally, you can use a naming convention for your discussion topics to give
+your students the audience context of their posts *before* they add them.
+Applying a naming convention can be useful if the students in your cohort
+groups are particularly sensitive about the privacy of their conversations.
+
+For example, you can use a naming convention such as "everyone" for unified
+course-wide discussion topics to distinguish them from topics that are divided
+by cohort. (You may only find it necessary to identify topics that offer a
+unified, public audience for all posts in this way. However, in this
+illustration, each topic has been given an identifier of either "everyone" or
+"private".)
+
+.. image:: ../Images/discussion_category_names.png
+ :alt: The names you supply for course-wide topics in Studio appear on the 
+       dropdown list of discussion topics in the live course
+
+When students visit the **Discussion** page and use dropdown lists to select
+one of the course-wide topics, the topic names indicate who can see the posts,
+responses, and comments.
+
+For more information about adding and configuring course-wide discussion
+topics, see :ref:`Organizing_discussions` or :ref:`Identifying Private
+CourseWide Discussion Topics`.
+
+If desired, you could also apply a naming convention to the content-specific
+discussion topics that you add as Discussion components in Studio. For example,
+you could include an identifier like "(private)" or "(small group)" in the
+**Subcategory** name of every Discussion component that you add.
+
+.. image:: ../Images/discussion_topic_names.png
+ :alt: The Subcategory name that you supply for a Discussion component in
+       Studio appears on the dropdown lists of discussion topics in the live
+       course

docs/en_us/course_authors/source/cohorts/cohorts_overview.rst

@@ -0,0 +1,255 @@
+.. _Cohorts Overview:
+
+##########################################
+Using Cohorts to Build Course Communities
+##########################################
+
+Cohorts create smaller communities of students within a course. Students who
+are in a cohort can communicate and share experiences privately within course
+discussion topics.
+
+When you enable the cohort feature for your course, the discussion topics
+that you include in units by adding discussion components are divided by
+cohort. This means that each post that a student makes to those 
+content-specific topics can only be read, and responded to, by members of the same
+cohort. However, any course-wide discussion topics that you set up for your
+course remain unified. This means that all posts can be read, and responded to,
+by every student. You can change some, or all, of your course-wide topics to be
+divided by cohort. See :ref:`Options for Discussion Topics`.
+
+This section also describes your options for :ref:`assigning students to cohort
+groups<Options for Assigning Students to Cohorts>`. When you enable the cohort
+feature, you define a set of cohort groups to reflect the student cohorts, and
+select a strategy for assigning students to the groups. Note that:
+
+* Every student must be assigned to a cohort group. This assures that every
+  student has the ability to read and contribute to all of the course
+  discussion topics.
+
+* Each student is in one and only one cohort group. 
+
+To provide a consistent experience throughout the course run, each student's
+assignment to a cohort group should remain unchanged after the course begins.
+
+For more information, see:
+
+* :ref:`Enabling and Configuring Cohorts`
+
+* :ref:`Moderating Discussions for Cohorts`
+
+For information about discussions, see :ref:`Discussions`.
+
+.. _Options for Discussion Topics:
+
+*********************************
+Options for Discussion Topics
+*********************************
+
+By enabling the cohort feature in a course, you provide students with the
+ability to ask questions of, and have conversations with, other members of
+their cohort. By offering these cohort-only discussion oppotunities, the cohort
+feature can help students develop a sense of community, provide specialized
+experiences, and encourage deeper, more meaningful course involvement.
+
+Enabling the cohort feature has different effects on the course-wide discussion
+topics and the content-specific discussion topics in the course.
+
+===================================================
+Course-Wide Discussion Topics Are Configurable
+===================================================
+
+To create course-wide discussion topics, you add them on the **Advanced
+Settings** page in Studio. By default, each of these topics is unified. All of
+the students in the course can post, read, respond, and comment in course-wide
+discussion topics without regard to their cohort group assignments. After you
+add a course-wide topic, you can configure it so that it is divided by cohort
+instead.
+
+For example, in addition to the General topic, which is supplied by default,
+you create these additional course-wide topics: Course Q&A, Announcements, and
+Brainstorming. You want all students to be able to read and contribute to all
+of the posts in the General and Course Q&A topics. However, you want the
+Announcements and Brainstorming topics to be divided, so that students will
+only be able to read and respond to contributions by the members of their own
+cohorts. You complete the additional configuration step for the Announcements
+and Brainstorming topics only.
+
+For information about course-wide discussion topics, see
+:ref:`Organizing_discussions`. For information about configuring these topics, 
+see :ref:`Configure CourseWide Discussion Topics as Private`.
+
+===================================================
+All Content-Specific Discussion Topics Are Divided
+===================================================
+
+Each of the content-specific discussion topics is divided by cohort. A student
+who is assigned to one cohort group cannot read or add to the posts, responses,
+or comments contributed by the members of another cohort group.
+
+To create content-specific discussion topics in a course, you add units that
+include discussion components. In a course with the cohort feature enabled, you
+do not have the option to change these topics to be unified for all students.
+
+For more information about content-specific discussion topics,
+see :ref:`Organizing_discussions`.
+
+.. _Options for Assigning Students to Cohorts:
+
+***********************************************
+Options for Assigning Students to Cohort Groups
+***********************************************
+
+You can configure the cohort feature so that students are assigned to cohort
+groups automatically or manually. You can also use a combination of both
+assignment methods. Typically, your purpose in including the cohort feature in
+your course determines which assignment option you will use for your course.
+
+* :ref:`All Automated Assignment`
+
+* :ref:`All Manual Assignment`
+
+* :ref:`Hybrid Assignment`
+
+* :ref:`Default Cohort Group`
+
+.. _All Automated Assignment:
+
+=============================================================
+Making MOOC Discussions Manageable: Automated Assignment
+=============================================================
+
+In very large courses, the number of posts made to course discussion topics can
+make for a daunting amount of daily reading. In such courses, dividing the
+enrollees into separate cohorts makes the volume of posts, responses, and
+comments by the members of each one more manageable, and is more likely to
+foster community feeling.
+
+To implement this assignment strategy, you enable the cohort feature and create
+a set of "auto" cohort groups. The first time a student views the course
+**Discussion** page or any of the content-specific discussion topics, he or she
+is randomly assigned to a cohort group. Together, all of the students assigned
+to a group are a cohort.
+
+These guidelines, which are based on the experiences of MOOC teams that have
+used the cohort feature in this way, are suggested to help you determine how
+many auto cohort groups to define for your course.
+
+* Each cohort should be large enough to inspire lively participation and
+  diverse points of view, but small enough to allow a sense of community to
+  develop. Cohorts formed by random assignment tend to be successful if they
+  include between 200 and 500 members.
+
+* For every 10,000 students who enroll, approximately 200 to 400 students
+  remain active in the discussions throughout the course run. 
+
+* Divide the estimated total enrollment of the course run by 10,000.
+
+* Use the result as the number of auto cohort groups to create.
+
+For example, two days before it starts, a course has an enrollment of 80,000
+students. To create small communities within the discussions, the course team
+enables the cohort feature and creates eight auto cohort groups. As they visit
+the **Discussion** page and view the discussion components in the course
+content, students are assigned to one of the cohorts. In divided discussion
+topics, students read and respond to contributions made by other members of the
+same cohort only.
+
+For more information, see :ref:`Implementing the Automated Assignment
+Strategy`.
+
+.. _All Manual Assignment:
+
+==========================================================
+Grouping by Common Characteristic: Manual Assignment
+==========================================================
+
+In SPOCs and other courses with small- to medium-sized enrollments, known
+existing commonalities can be used to identify cohorts. An example is a course
+that enrolls students from different companies or with different educational
+backgrounds, or members of alumni or parent groups. When students are assigned
+to cohorts on the basis of a characteristic that they share, they can privately
+discuss applications for what they are learning and explore resources and ideas
+that are of particular interest.
+
+To implement this assignment strategy, you identify the "real-world" cohorts
+that your students belong to already. You enable the cohort feature and create
+a "manual" cohort group to represent each of those cohorts. You then assign
+each student to one of the manual cohort groups. Every student who enrolls,
+including those who enroll after the course starts, must be assigned to a
+cohort group.
+
+.. note:: To ensure that every student is assigned to a cohort group, you can 
+ set up a single auto cohort group, as described for the :ref:`hybrid
+ assignment strategy<Hybrid Assignment>`. If you do not create an auto cohort
+ group, the system automatically creates a :ref:`default cohort group<Default
+ Cohort Group>` and assignes students to it if necessary.
+
+For more information, see :ref:`Implementing the Manual Assignment Strategy`.
+
+.. _Hybrid Assignment:
+
+=============================================================
+Accomodating Small Groups Within a Course: Hybrid Assignment
+=============================================================
+
+For some courses, the manual assignment strategy isn't feasible to execute, and
+the automated assignment strategy doesn't accommodate the existing cohorts that
+exist in the student body. The enrollment may be too large to complete manual
+assignments effectively, or only some of the students may have strong defining
+characteristics among an otherwise diverse student body. For these courses, you
+can use a hybrid of the two strategies to implement the cohort feature.
+
+An example is a course that enrolls members of an alumni association. The
+alumni want an opportunity for private interactions, so manual assignment of
+those students to a cohort group makes sense. For other students in the class,
+manual assignment isn't needed: you create one or more auto cohort groups for
+those students.
+
+Before you implement the hybrid strategy, you identify the characteristics that
+define existing cohorts in the student body. You also decide whether you want
+the rest of the students in the course to be divided into their own, 
+similarly-sized cohort groups, or if you want them all to be in just one other 
+group.
+
+After you enable the cohort feature, you create a manual cohort group for each
+cohort that you identified. You manually assign students who belong to those
+cohorts to the corresponding groups. You also set up auto cohort groups for
+the other students in the course, or rely on the default cohort group. The
+students who are not assigned to a manual cohort group are automatically
+assigned to one of the auto cohort groups, or to the default cohort group if
+you choose to use it, when they view the **Discussion** page or a discussion
+topic in the course content. (For best results when you use this strategy, you
+complete all manual assignments before the course starts and students begin
+viewing discussion topics.)
+
+For more information, see :ref:`Implementing the Automated Assignment
+Strategy` and :ref:`Implementing the Manual Assignment Strategy`.
+
+.. _Default Cohort Group:
+
+==================================================================
+Assuring That All Students Are Assigned: The Default Cohort Group
+==================================================================
+
+In a course that has the cohort feature enabled, all students must be assigned
+to a cohort group. To assure that all students are assigned, the system
+automatically creates a default cohort group and assigns students to it if
+necessary. Creation of the default cohort group only occurs if you do not
+define any auto cohort groups for your course. Any student who is not assigned
+to a manual cohort group is assigned to the default cohort group automatically
+when they visit the **Discussion** page or a discussion topic in the course
+content.
+
+Students who are assigned to the default cohort group see a cohort name of
+"Default Group" in discussion posts. See :ref:`Read the Cohort Indicator in
+Posts`. If you want students to see a different cohort name, add an auto cohort
+group with the name that you prefer. See :ref:`Define Auto Cohort Groups`.
+
+You can check the :ref:`student profile information report<View and download
+student data>` for your course to see if any students are assigned to the
+default cohort group in your course, and change their group assignments. Note,
+however, that in divided discussion topics students can only see posts by
+members of their currently assigned cohort group: when a student is reassigned,
+posts "disappear". As a result, any group assignment changes should be done as
+early in the course run as possible so that students see discussion posts and
+contributions that remain consistent over time.

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

@@ -0,0 +1,12 @@
+.. _Including Student Cohorts:
+
+#############################
+Including Student Cohorts
+#############################
+
+.. toctree::
+   :maxdepth: 2
+   
+   cohorts_overview
+   cohort_config
+   cohorts_discussions

docs/en_us/course_authors/source/getting_started/glossary.rst

@@ -81,10 +81,15 @@ C
 
 .. _Cohort:
  
-.. **Cohort**
+**Cohort**
 
-..  A group of students that participate in the class together. A cohort can have forum discussions apart from the rest of the students.
+  A group of students who participate in a class together. Students who are in
+  the same cohort group can communicate and share experiences in private
+  discussions.
 
+  Cohorts are an optional feature of courses on the edX platform. For
+  information about how you enable the cohort feature, set up cohort groups,
+  and assign students to them, see :ref:`Cohorts Overview`.
 
 .. _Component_g:
  
@@ -104,6 +109,17 @@ C
   exposed to different versions of of the content. For more information, see
   :ref:`Creating Content Experiments`.
 
+**Content-Specific Discussion Topic**
+
+  A category within the course discussion that appears at a defined point in
+  the course to encourage questions and conversations. To add a 
+  content-specific discussion topic to your course, you add a discussion 
+  component to a unit. Students cannot contribute to a content-specific 
+  discussion topic until the release date of the section that contains it.
+
+  For more information, see :ref:`Working with Discussion Components` and
+  :ref:`Organizing_discussions`.
+
 .. _Course Accordion:
  
 **Course Accordion**
@@ -148,6 +164,14 @@ C
 
   The page where students access the primary instructional materials for your course. Sections, subsections, units, and components are all accessed from the Courseware page.
 
+**Course-Wide Discussion Topic**
+
+  Optional categories that you create to guide how students find and share
+  information in the course discussion. Examples of course-wide discussion
+  topics include Announcements and Frequently Asked Questions. Students can
+  contribute to these topics as soon as your course starts.
+
+  For more information, see :ref:`Organizing_discussions`.
 
 .. _Custom Response Problem:
  
@@ -191,7 +215,11 @@ D
  
 **Discussion Component**
 
-  Discussion topics that course staff add directly to units. For example, a Video component can be followed by a Discussion component so that students can discuss the video content without having to leave the page.
+  Discussion topics that course staff add directly to units. For example, a
+  Video component can be followed by a Discussion component so that students
+  can discuss the video content without having to leave the page. When you add
+  a dicussion component to a unit, you create a content-specific discussion
+  topic.
 
   See :ref:`Working with Discussion Components` for more information.
 

docs/en_us/course_authors/source/index.rst

@@ -20,6 +20,7 @@ Building and Running an edX Course
    creating_content/index
    exercises_tools/index
    content_experiments/index
+   cohorts/index
    releasing_course/index
    running_course/index
    students/index

docs/en_us/course_authors/source/releasing_course/course_launching.rst

@@ -32,6 +32,9 @@ starts follow.
   Dates for Your Course`.
 * Review the grading policy, and set a grace period for homework assignment
   due dates. See :ref:`Establish a Grading Policy`.
+* Confirm that any optional features that you want your course to include, such
+  as implementing student cohorts, are enabled and configured. See
+  :ref:`Cohorts Overview`.
 
 **Review First Week Content**
 

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

@@ -65,12 +65,12 @@ enrolls them in each selected course.
 You can access this self-reported information for all of the students who are
 enrolled in your course:
 
-* email
 * username
 * name
-* level_of_education
-* gender
+* email
 * year_of_birth
+* gender
+* level_of_education
 * mailing_address
 * goals
 
@@ -82,7 +82,8 @@ names at any time. As a result, you may want to download student data
 periodically to gain insights into how the student population changes over
 time.
 
-.. note:: In the future, edX may also request that students select a language and location. This data is not collected at this time.
+.. note:: In the future, edX may also request that students select a language 
+ and location. This data is not collected at this time.
 
 .. _View and download student data:
 
@@ -90,40 +91,71 @@ time.
 Download or View Student Data
 ==========================================
 
-You can download student data to learn about population demographics at a
-specific point in time, compare demographics at different points in time, and
-plot trends in the population over time.
+You can download a report of the self-reported student data to learn about
+population demographics at a specific point in time, compare demographics at
+different points in time, and plot trends in the population over time. For
+courses that include student cohorts, this report also includes the cohort
+group that is assigned to each student.
 
-In addition to the data for enrolled students, data for the course staff is
-included in the file or display.
+When you choose to download student data, a process starts on the edX servers.
+The number of students enrolled in your course, and whether your course has the
+cohort feature enabled, affect how long this process takes. You can download a
+report of student profile information in a CSV (comma-separated values) file
+after the process is complete.
 
-.. important:: Do not navigate away from this page while you wait for the data to be prepared. The larger the enrollment for your course, the longer it takes to create and output the data. 
+For courses with fewer than 200 students enrolled, you also have the option to
+view student data on the Instructor Dashboard.
 
-For smaller courses, you also have the option to view student data on the
-Instructor Dashboard.
+.. note:: In addition to the data for enrolled students, data for the course 
+ staff is included in the file or display.
 
-To download or view student data:
+To download student data:
 
 #. View the live version of your course.
 
 #. Click **Instructor**, then click **Data Download**.
 
-#. To download data about enrolled students in a CSV file, click **Download profile information as a CSV**.
+#. To download data about enrolled students in a CSV file, click **Download
+   profile information as a CSV**.
 
-   You are prompted to open or save the enrolled_profiles.csv file. All
-   student-supplied data is included without truncation.
+  A status message indicates that report generation is in progress. This
+  process can take some time to complete, but you can navigate away from this
+  page and do other work while it runs.
+
+  To track the progress of the report process, reload the page in your browser
+  and scroll down to the **Pending Instructor Tasks** section.
+
+4. To open or save a student data report, click the
+   ``{course_id}_enrolled_profiles_{date}.csv`` file name at the bottom of the
+   page.
+
+  All student-supplied data is included in this file without truncation.
+
+To view student data:
+
+.. note:: This option is available only for courses with an enrollment of less 
+ than 200.
+
+#. View the live version of your course.
+
+#. Click **Instructor**, then click **Data Download**.
 
 #. To display data about enrolled students, click **List enrolled students'
-   profile information**. (This option is available only for courses with an
-   enrollment of less than 200.)
+   profile information**. 
 
    A table of the student data displays, with one row for each enrolled
    student. Longer values, such as student goals, are truncated.
 
  .. image:: ../Images/StudentData_Table.png
-  :alt: Table with columns for the collected data points and rows for each student on the Instructor Dashboard
+  :alt: Table with columns for the collected data points and rows for each 
+        student on the Instructor Dashboard
 
-.. note:: The columns for language and location are included in this report for backward compatibility only. This data is no longer collected during student registration.
+For courses that have the cohorts feature enabled, this report also includes a
+Cohort column with each student's assigned cohort group.
+
+.. note:: The columns for language and location are included in this report 
+ for backward compatibility only. This data is no longer collected during
+ student registration.
 
 ==========================================
 View Demographic Distributions

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

@@ -19,12 +19,17 @@ sections:
 
 * :ref:`Organizing_discussions`
 
+* :ref:`Assigning_discussion_roles`
+
 * :ref:`Running_discussions`
 
 * :ref:`Moderating_discussions`
 
 * :ref:`Close_discussions`
   
+For information about how enabling the cohort feature for a course affects the 
+course discussions, see :ref:`Moderating Discussions for Cohorts`.
+
 .. _Overview_discussions:
 
 ********************************
@@ -80,12 +85,20 @@ Add Units With a Discussion Component
 
 Typically, all units are added during the design and creation of your course in
 Studio. To add a discussion topic to a unit, you add a discussion component.
-Follow the instructions in :ref:`Working with Discussion Components`.
+Follow the instructions in :ref:`Working with Discussion Components`. The
+result is a content-specific discussion topic.
 
 This type of discussion topic is subject to the release date of the section
 that contains it. Students cannot contribute to these discussion topics until
 that date.
 
+.. note:: In courses that include the cohort feature, all of the 
+ content-specific discussion topics are private. Student posts to these topics
+ can only be read, and responded to, by members of the same cohort group. See
+ :ref:`Cohorts Overview`.
+
+.. _Create CourseWide Discussion Topics:
+
 =====================================
 Create Course-Wide Discussion Topics
 =====================================
@@ -107,37 +120,49 @@ To create a course-wide discussion topic:
    value is:
 
  .. image:: ../Images/Discussion_Add_initial.png
-  :alt: Policy value of {"General": {"id": "i4x-edX-Open_DemoX-course-edx_demo_course"}}
+  :alt: Policy value of {"General": {"id": "i4x-edX-Open-edx_demo_course"}}
 
 4. Copy the three lines provided for the General topic and paste
-   them above the closing brace:
+   them above the closing brace character (``}``):
 
  .. image:: ../Images/Discussion_Add_paste.png
-  :alt: Policy value of {"General": {"id": "i4x-test_doc-SB101-course-2014_Jan"} "General": {"id": "i4x-test_doc-SB101-course-2014_Jan"}}
+  :alt: Policy value of {"General": {"id": "i4x-edX-Open-edx_demo_course"} 
+        "General": {"id": "i4x-edX-Open-edx_demo_course"}}
 
 5. Replace the second "General" with the quoted name of your new topic.
 
-#. Change the second id value to a unique identifier. For example, append a
-   reference to the name of the topic.
+#. Change the value for the second "id" to a unique identifier. For example,
+   append a reference to the name of the topic.
 
-#. Add a comma after the first closing brace.
+#. Add a comma after the first closing brace (``},``).
 
  .. image:: ../Images/Discussion_Add_name.png
-  :alt: Policy value of {"General": {"id": "i4x-test_doc-SB101-course-2014_Jan"}, "Course Q&A": {"id": "i4x-test_doc-SB101-course-2014_Jan_faq"}}
+  :alt: Policy value of {"General": {"id": "i4x-edX-Open-edx_demo_course"}, 
+        "Course Q&A": {"id": "i4x-edX-Open-edx_demo_course_faq"}}
 
-8. Click **Save Changes**.
+8. Click **Save Changes**. Studio resequences and reformats your entry. Scroll
+   back to the **Discussion Topic Mapping** field to verify that your entry was
+   saved as you expect. Entries that do not contain all of the required
+   punctuation characters revert to the previous value when you save, and no
+   warning is presented.
 
 When students click the **Discussion** page for your course, the drop-down
-Discussion list now includes this topic.
+Discussion list now includes the topic you added.
 
  .. image:: ../Images/NewCategory_Discussion.png
   :alt: Image of a new topic named Course Q&A in the list of discussions
 
+.. note:: In courses that include the cohort feature, the course-wide 
+ discussion topics that you add are public. All of the posts can be read, and
+ responded to, by every student, regardless of their assignement to a cohort
+ group. You can configure course-wide discussion topics to be private. See
+ :ref:`Identifying Private CourseWide Discussion Topics`.
+
 .. _Assigning_discussion_roles:
 
-==========================================
+*************************************************
 Assign Discussion Administration Roles 
-==========================================
+*************************************************
 
 You can designate a team of people to help you run course discussions.
 
@@ -169,7 +194,7 @@ these roles:
   by community TAs have a colored "Community TA" identifier. This role is often
   given to students.
 
-.. put this comment in to make the formatting of this bulleted list consistent when output using the spinx template
+.. I put this comment in to make the formatting of this bulleted list consistent when output using the sphinx template
 
 * *Discussion admins* have the same options for working with discussions as
   moderators, and their posts, responses, and comments have the same "Staff"
@@ -188,8 +213,13 @@ addresses or usernames.
 * 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
-are identified in Studio as a team member with Admin access).
+====================================
+Assign Roles
+====================================
+
+To assign a discussion administration role, you must be the course author or an
+Instructor (that is, you are identified in Studio as a team member with Admin
+access).
 
 #. View the live version of the course.
 

docs/en_us/shared/browsers.rst

@@ -110,4 +110,4 @@ students.
      - Yes
      - Yes
      - N/A
-     - N/A
+     - N/A