diff --git a/docs/en_us/course_authors/source/Images/a-b-test-lms-group-0.png b/docs/en_us/course_authors/source/Images/a-b-test-lms-group-0.png new file mode 100644 index 0000000000..e48a88ad05 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/a-b-test-lms-group-0.png differ diff --git a/docs/en_us/course_authors/source/Images/a-b-test-lms-group-2.png b/docs/en_us/course_authors/source/Images/a-b-test-lms-group-2.png new file mode 100644 index 0000000000..c491e40710 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/a-b-test-lms-group-2.png differ diff --git a/docs/en_us/course_authors/source/Images/a-b-test-studio_unit_page.png b/docs/en_us/course_authors/source/Images/a-b-test-studio_unit_page.png new file mode 100644 index 0000000000..0e5816a559 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/a-b-test-studio_unit_page.png differ diff --git a/docs/en_us/course_authors/source/Images/a_b_test_child_expanded.png b/docs/en_us/course_authors/source/Images/a_b_test_child_expanded.png new file mode 100644 index 0000000000..d064d72402 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/a_b_test_child_expanded.png differ diff --git a/docs/en_us/course_authors/source/Images/a_b_test_children.png b/docs/en_us/course_authors/source/Images/a_b_test_children.png new file mode 100644 index 0000000000..1baa9a7a1a Binary files /dev/null and b/docs/en_us/course_authors/source/Images/a_b_test_children.png differ diff --git a/docs/en_us/course_authors/source/Images/child-components-a.png b/docs/en_us/course_authors/source/Images/child-components-a.png new file mode 100644 index 0000000000..4874398e2e Binary files /dev/null and b/docs/en_us/course_authors/source/Images/child-components-a.png differ diff --git a/docs/en_us/course_authors/source/Images/child-components.png b/docs/en_us/course_authors/source/Images/child-components.png new file mode 100644 index 0000000000..477437e4fb Binary files /dev/null and b/docs/en_us/course_authors/source/Images/child-components.png differ diff --git a/docs/en_us/course_authors/source/Images/component_container.png b/docs/en_us/course_authors/source/Images/component_container.png new file mode 100644 index 0000000000..d70ee3818d Binary files /dev/null and b/docs/en_us/course_authors/source/Images/component_container.png differ diff --git a/docs/en_us/course_authors/source/Images/conex_selectgroupconfig.png b/docs/en_us/course_authors/source/Images/conex_selectgroupconfig.png new file mode 100644 index 0000000000..1ba791cedd Binary files /dev/null and b/docs/en_us/course_authors/source/Images/conex_selectgroupconfig.png differ diff --git a/docs/en_us/course_authors/source/Images/container_pub_status.png b/docs/en_us/course_authors/source/Images/container_pub_status.png new file mode 100644 index 0000000000..1be699bf7e Binary files /dev/null and b/docs/en_us/course_authors/source/Images/container_pub_status.png differ diff --git a/docs/en_us/course_authors/source/Images/content_experiment_block.png b/docs/en_us/course_authors/source/Images/content_experiment_block.png new file mode 100644 index 0000000000..403449713e Binary files /dev/null and b/docs/en_us/course_authors/source/Images/content_experiment_block.png differ diff --git a/docs/en_us/course_authors/source/Images/content_experiment_container.png b/docs/en_us/course_authors/source/Images/content_experiment_container.png new file mode 100644 index 0000000000..30185ddbce Binary files /dev/null and b/docs/en_us/course_authors/source/Images/content_experiment_container.png differ diff --git a/docs/en_us/course_authors/source/Images/content_experiment_editor.png b/docs/en_us/course_authors/source/Images/content_experiment_editor.png new file mode 100644 index 0000000000..7765b95a7b Binary files /dev/null and b/docs/en_us/course_authors/source/Images/content_experiment_editor.png differ diff --git a/docs/en_us/course_authors/source/Images/content_experiment_editor_group2.png b/docs/en_us/course_authors/source/Images/content_experiment_editor_group2.png new file mode 100644 index 0000000000..2604156898 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/content_experiment_editor_group2.png differ diff --git a/docs/en_us/course_authors/source/Images/content_experiment_group_config_link.png b/docs/en_us/course_authors/source/Images/content_experiment_group_config_link.png new file mode 100644 index 0000000000..4bd2c746f8 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/content_experiment_group_config_link.png differ diff --git a/docs/en_us/course_authors/source/Images/content_experiment_page_group_config_link.png b/docs/en_us/course_authors/source/Images/content_experiment_page_group_config_link.png new file mode 100644 index 0000000000..6eaaca8b79 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/content_experiment_page_group_config_link.png differ diff --git a/docs/en_us/course_authors/source/Images/create-group-config.png b/docs/en_us/course_authors/source/Images/create-group-config.png new file mode 100644 index 0000000000..fe71ef829e Binary files /dev/null and b/docs/en_us/course_authors/source/Images/create-group-config.png differ diff --git a/docs/en_us/course_authors/source/Images/drag_child_component.png b/docs/en_us/course_authors/source/Images/drag_child_component.png new file mode 100644 index 0000000000..9e99c57500 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/drag_child_component.png differ diff --git a/docs/en_us/course_authors/source/Images/group-configuration-delete.png b/docs/en_us/course_authors/source/Images/group-configuration-delete.png new file mode 100644 index 0000000000..384ff2d0ad Binary files /dev/null and b/docs/en_us/course_authors/source/Images/group-configuration-delete.png differ diff --git a/docs/en_us/course_authors/source/Images/group_configurations.png b/docs/en_us/course_authors/source/Images/group_configurations.png new file mode 100644 index 0000000000..b0a775e78e Binary files /dev/null and b/docs/en_us/course_authors/source/Images/group_configurations.png differ diff --git a/docs/en_us/course_authors/source/Images/group_configurations_edit.png b/docs/en_us/course_authors/source/Images/group_configurations_edit.png new file mode 100644 index 0000000000..59a6b715e9 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/group_configurations_edit.png differ diff --git a/docs/en_us/course_authors/source/Images/group_configurations_experiments.png b/docs/en_us/course_authors/source/Images/group_configurations_experiments.png new file mode 100644 index 0000000000..4a3de76bc3 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/group_configurations_experiments.png differ diff --git a/docs/en_us/course_authors/source/Images/group_configurations_one_listed.png b/docs/en_us/course_authors/source/Images/group_configurations_one_listed.png new file mode 100644 index 0000000000..c0d8211e4e Binary files /dev/null and b/docs/en_us/course_authors/source/Images/group_configurations_one_listed.png differ diff --git a/docs/en_us/course_authors/source/Images/inactive_groups.png b/docs/en_us/course_authors/source/Images/inactive_groups.png new file mode 100644 index 0000000000..a527fa6e60 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/inactive_groups.png differ diff --git a/docs/en_us/course_authors/source/Images/nested_components_student_view.png b/docs/en_us/course_authors/source/Images/nested_components_student_view.png new file mode 100644 index 0000000000..df4a5fc1e6 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/nested_components_student_view.png differ diff --git a/docs/en_us/course_authors/source/Images/save-group-config.png b/docs/en_us/course_authors/source/Images/save-group-config.png new file mode 100644 index 0000000000..2727853f75 Binary files /dev/null and b/docs/en_us/course_authors/source/Images/save-group-config.png differ diff --git a/docs/en_us/course_authors/source/change_log.rst b/docs/en_us/course_authors/source/change_log.rst index 6cc0c5a348..c1b653540d 100644 --- a/docs/en_us/course_authors/source/change_log.rst +++ b/docs/en_us/course_authors/source/change_log.rst @@ -16,6 +16,8 @@ August, 2014 - Updated documentation in :ref:`Developing Your Course Index` for new capabilities to publish or hide multiple units from the outline. + * - + - Added documentation for :ref:`Creating Content Experiments` * - 08/22/14 - Added warnings about the effects of changing the course grading policy, graded subsections, or graded components after the course begins. diff --git a/docs/en_us/course_authors/source/content_experiments/content_experiments_add.rst b/docs/en_us/course_authors/source/content_experiments/content_experiments_add.rst new file mode 100644 index 0000000000..f472245f39 --- /dev/null +++ b/docs/en_us/course_authors/source/content_experiments/content_experiments_add.rst @@ -0,0 +1,239 @@ +.. _Add Content Experiments to Your Course: + +######################################### +Add Content Experiments to Your Course +######################################### + +After you :ref:`enable content experiments ` and +:ref:`set up group configurations in Studio ` or :ref:`in XML `, you +can add content experiments to your course. See: + +* :ref:`Add a Content Experiment in Studio` +* :ref:`Add a Content Experiment in XML` + +.. _Add a Content Experiment in Studio: + +******************************************** +Add a Content Experiment in Studio +******************************************** + +You can add a content experiment in a unit or container page. In Studio, you +create and view content for all groups in the content experiment in a container +page for the experiment, as shown in `Create Content for Groups in the Content +Experiment`_. + +When a student views the unit with the content experiment, she has no +indication there is a content experiment in the unit, and the content +experiment display name is not shown. She sees only the content that you +configure for the group she is assigned to. To the student, the unit with the +content experiment is no different than any other unit. + +To configure a content experiment in Studio, you: + +#. `Create the content experiment`_. +#. `Create content for groups in the content experiment`_. + +After you configure a content experiment, you can `change the +group configuration `_. + +=============================== +Create the Content Experiment +=============================== + +#. In the unit page, under **Add New Component**, click **Advanced**. + +#. Select **Content Experiment**. + + A new content experiment is added to the unit: + + .. image:: ../Images/content_experiment_block.png + :width: 800 + :alt: The content experiment component in a unit page + + You can work with the content experiment as you can any other component. + See :ref:`Components` for more information. + +#. Click either **Select a Group Configuration** or **Edit** to open the content + experiment component. + + .. image:: ../Images/content_experiment_editor.png + :alt: The content experiment editor + +#. Next to **Group Configuration**, select a group configuration. + +#. In the **Display Name** field, enter the name that the component will use in Studio. The + display name is only used in Studio; students do not see this value. + +#. Click **Save**. + +The content experiment is displayed as a component that contains other +components. See :ref:`Components that Contain Other Components` for more +information. + +.. note:: You cannot duplicate a content experiment. + +You can now create content for the groups in the experiment. + +===================================================== +Create Content for Groups in the Content Experiment +===================================================== + +After you select a group configuration, in the content experiment component, +click **View**. + +The content experiment page that opens automatically includes a container for +each group that is defined in the group configuration you selected. For +example, if you select a group configuration that defines Group A and Group B, +you see the following page: + +.. image:: ../Images/content_experiment_container.png + :alt: The content experiment page with two groups + +You add content for both groups as needed, just as you would add content to any +container page. See :ref:`Components that Contain Other Components` for more +information. + +For example, you can add an HTML component and a video to Group A: + +.. image:: ../Images/a_b_test_child_expanded.png + :alt: Image of an expanded A/B test component + +.. note:: + It is valid, and can be useful, to have no content for a group in the + experiment. For example, if one group has a video and another group has no + content, you can analyze the effect of the video on student performance. + + +======================================================== +Change the Group Configuration for a Content Experiment +======================================================== + +You can change the group configuration for a content experiment. When you +change the group configuration, you must add components to any new groups that you create. You +can use the components from the previous groups, as well as create new +components. + +.. warning:: + Changing the group configuration of a student-visible experiment will affect + the experiment data. + +To change the group configuration: + +#. Open the unit page of the unit that contains the content experiment. + +#. In the content experiment component, click **Edit**. + + .. image:: ../Images/content_experiment_editor_group2.png + :alt: The content experiment editor with a group configuration selected + +#. Select a different group configuration. + +#. Click **Save**. + +#. You must now add components to the new groups in the experiment. Click + **View** to open the content experiment. + + You see that groups for the new configuration are empty, and any components + that you had added to groups in the previous configuration are now moved to + a section called **Inactive Groups**. + + .. image:: ../Images/inactive_groups.png + :alt: Components in inactive groups + +#. Drag and drop components from the **Inactive Groups** section into the new + groups. You can also create new components in the new groups. + + +.. _Add a Content Experiment in XML: + +**************************************** +Add a Content Experiment in XML +**************************************** + +If you are developing your course in XML, you work with multiple XML files to +configure a content experiment. This section steps through the files involved +in a content experiment that shows different content to two different groups of +students. + +For more information about working with your course's XML files, including +information about terminology, see the `edX XML Tutorial +`_. + +===================================================== +Define the Content Experiment in the Sequential File +===================================================== + +You reference a content experiment in the file for the subsection in the +``sequential`` directory. For example: + +.. code-block:: xml + + ... + + + + ..... + +The ```` element's ``url_name`` value references the name of the +A/B test file in the ``split_test`` directory. + + +.. _Define the Experiment Content in the Split Test File: + +===================================================== +Define the Experiment Content in the Split Test File +===================================================== + +After you define the content experiment in the sequential file, you define the +course content you want to test in the file in the ``split_test`` directory. +This is the file referenced in the ```` element in the sequential +file, as shown above. + +In the content experiment file, you add elements for the experiment content. +For this example, you add two ```` elements to compare the two +different sets of content. + +.. code-block:: xml + + + + Welcome to group A. + + + Welcome to group B. + +

A checkboxes problem presents checkbox buttons for student input. + Students can select more than one option presented.

+ + + correct + incorrect + correct + + + + + + + +In this example: + +* The ``user_partition_id`` value references the ID of the experiment defined + in the ``policy.json`` file. + +* The ``group_id_to_child`` value references the IDs of the groups defined in + the ``policy.json`` file and maps the group IDs to specific content. + + For example, the value for group ``0``, ``i4x://path-to- + course/vertical/group_a``, maps to the ```` element with the + ``url_name`` equal to ``group_a``. Therefore, students in group 0 see the + content in that vertical. + +For information about the ``policy.json`` file, see :ref:`Set up Group +Configurations in an XML Course`. \ No newline at end of file diff --git a/docs/en_us/course_authors/source/content_experiments/content_experiments_configure.rst b/docs/en_us/course_authors/source/content_experiments/content_experiments_configure.rst new file mode 100644 index 0000000000..e977bdbf9c --- /dev/null +++ b/docs/en_us/course_authors/source/content_experiments/content_experiments_configure.rst @@ -0,0 +1,398 @@ +.. _Configure Your Course for Content Experiments: + +##################################################### +Configure Your Course for Content Experiments +##################################################### + +This chapter describes how to configure your course so that you can use content +experiments. See: + +* :ref:`Enable Content Experiments` +* :ref:`Overview of Group Configurations` +* :ref:`Set up Group Configurations in edX Studio` +* :ref:`Guidelines for Modifying Group Configurations` +* :ref:`Set up Group Configurations in an XML Course` + +.. _Enable Content Experiments: + +**************************************** +Enable Content Experiments +**************************************** + +To enable content experiments in your course, you add ``split_test`` to the +**Advanced Modules List** in Advanced Settings. + +.. note:: + ``split_test`` is the internal edX Platform name for a content experiment. + +#. From the **Settings** menu, select **Advanced Settings**. +#. On the **Advanced Settings** page, locate **Advanced Modules List**. +#. In the **Advanced Modules List** field, add ``"split_test"``. Be sure that +you include the double quotation marks. + + If you have multiple values, ensure that they are separated by commas + (``,``). + + For example, the text in the **Advanced Modules List** field may resemble the following: + + .. code-block:: json + + [ + "lti", + "word_cloud", + "split_test" + ] + +#. At the bottom of the page, click **Save Changes**. + +.. _Overview of Group Configurations: + +**************************************** +Overview of Group Configurations +**************************************** + +Before you can create content experiments, you must specify at least one group +configuration for your course. + +A group configuration defines how many groups of students are in an experiment. +You can have any number of group configurations in your course. When you create +a content experiment, you select the group configuration to use. + +For example, you may want to do two different experiments at different times during +your course. In one content experiment, students either see a video or complete a +video or a reading assignment. You can then include problems so that you can see +which group learned the material more completely. For this content experiment, you +need a group configuration that assigns your students to two groups. + +In the other content experiment, you can present the same question using four +different types of problem. For this content experiment, you need a +group configuration that assigns your students to four groups. + +============================= +Assigning Students to Groups +============================= + +The edX Platform assigns students to each group in a group configuration. + +Group assignments are: + +* Dynamic + + The edX Platform assigns a student to a group the first time he or she views + a content experiment that uses the group configuration. + +* Random + + You cannot control which students are assigned to which group. + +* Evenly distributed + + The edX Platform keeps track of the size of groups and assigns new students + to groups evenly. For example, when there are two groups in a configuration, + each group will include 50% of the students in the course; when you have four + groups, each group will include 25%. + +* Permanent + + Students remain in their assigned groups regardless of how many content + experiments you set up that use the same group configuration. + +.. _Set up Group Configurations in edX Studio: + +************************************************ +Set up Group Configurations in edX Studio +************************************************ + +..note:: You must :ref:`enable content experiments` before you can set up group configurations. + +To set up group configurations, on the **Settings** menu, select **Group +Configurations**. The **Group Configurations** page opens: + +.. image:: ../Images/group_configurations.png + :width: 800 + :alt: The Group Configurations page + +From this page you can :ref:`create`, +:ref:`edit`, and :ref:`delete` group configurations. You can also :ref:`view experiments that +use a group configuration`. + +.. _Create a Group Configuration: + +============================= +Create a Group Configuration +============================= + +You can create a group configuration at any time. + +#. On the **Group Configurations** page, click **Add Your First Group Configuration**. The + following page opens: + + .. image:: ../Images/create-group-config.png + :width: 800 + :alt: Create a New Group Configuration page + +2. Enter a name in the **Group Configuration Name** field. Use a meaningful + name, as you select from group configuration names when creating content + experiments. Students will not see the name. + +#. Optionally, enter a description for the new group configuration. +#. By default, a new configuration already contains two groups. Modify the + names of those groups or add new groups as needed: + + * Modify the group names as needed. You see group names in the unit page in + Studio; students do not see group names. + * Click **Add another group** to include another group as part of the + configuration. + * Click the **X** to the right of an existing group to remove it from the + configuration. A group configuration must have at least one group. + +5. Click **Create** to save the new group configuration. + +The group configuration is then listed in the page. You can see the number of groups that the configuration contains, as well as whether the configuration is in use in the course: + +.. image:: ../Images/group_configurations_one_listed.png + :width: 800 + :alt: The Group Configurations page with one group configuration + +.. _Edit a Group Configuration: + +============================= +Edit a Group Configuration +============================= + +.. important:: + You can change the name of a group configuration at any time. However, + before you modify any other characteristics of a group that is inside a group configuration + that is currently used in a running course, review `Guidelines for Modifying Group + Configurations`_. + +#. On the **Group Configurations** page, hover over the group configuration and + click **Edit**. + + .. image:: ../Images/group_configurations_edit.png + :alt: The Group Configurations page with Edit button + + The following page opens: + + .. image:: ../Images/save-group-config.png + :alt: Edit a Group Configuration page + +#. Modify the name and description as needed. + +#. Modify groups in the configuration as needed. See `Create a Group + Configuration`_ for details. + +#. Click **Save** to save your changes. + +.. _Delete a Group Configuration: + +============================= +Delete a Group Configuration +============================= + +.. note:: + You can only delete a group configuration that is not currently used in a content + experiment. You cannot delete a group configuration that is used in a content experiment. + +#. On the **Group Configurations** page, hover over the group configuration and + click the Delete icon. + + .. image:: ../Images/group-configuration-delete.png + :alt: Edit a Group Configuration page + +2. When prompted to confirm the deletion, click **Delete**. + +.. _View Experiments that Use a Group Configuration: + +=============================================== +View Experiments that Use a Group Configuration +=============================================== + +When working with group configurations, you can view the experiments that use +each configuration. + +On the **Group Configurations** page, click the name of a group to expand the group +and see its details. You see links to experiments that use the group configuration: + +.. image:: ../Images/group_configurations_experiments.png + :alt: A group configuration with the experiments using it circled + +Click a link to go to the unit page that contains the experiment. + +=============================================== +View a Group Configuration from an Experiment +=============================================== + +When working with a content experiment, you can view details about the group +configuration used by that experiment. + +On the unit page for a unit that contains a content experiment, click the name of the group +configuration. + +.. image:: ../Images/content_experiment_group_config_link.png + :alt: Content experiment in the unit page with the group configuration link + circled + +Or at the top of the content experiment page, click the name of the group +configuration. + +.. image:: ../Images/content_experiment_page_group_config_link.png + :alt: Content experiment page with the group configuration link circled + +In both cases, the group configuration opens: + +.. image:: ../Images/group_configurations_experiments.png + :alt: A Group Configuration with the experiments using it circled + +You can use the link in the group configuration to return to the unit that +contains the content experiment. + + +.. _Guidelines for Modifying Group Configurations: + +********************************************* +Guidelines for Modifying Group Configurations +********************************************* + +Review these guidelines if you must modify a group configuration after a course +starts. These guidelines apply for courses built in Studio or XML. + + +================================== +Modifying a Group Configuration +================================== + +After the course starts, **do not**: + +* Delete group configurations. + +* Change the ``id`` value of a group configuration. + + +================= +Modifying Groups +================= + +After the course starts, **do not** change the ``id`` value of a group. + +You can change group names at any time. + +========================================================== +Removing Groups from Group Configurations +========================================================== + +After a course has started, you may find that students in a specific group are +having difficulties or a poor experience. In this situation, you can remove the +group from the group configuration. Content that was specified for that +group is then no longer visible to students. + +Students in the removed group are reassigned evenly to one of the other groups +in the group configuration. Any problems that these students completed in the +removed group content do not count toward the students' grades. The students +must begin the problem set again and complete all the problems in the group +content to which they've been reassigned. + +Removing a group affects the course event data. Ensure that researchers +evaluating your course results are aware of the group you removed and the +date you removed it. + +.. _Set up Group Configurations in an XML Course: + +************************************************ +Set up Group Configurations in an XML Course +************************************************ + +If you are developing your course in XML, you define group configurations in +the ``policy.json`` file in the ``policies`` directory. + +See :ref:`Add a Content Experiment in XML` for more information on how the XML +for the content experiment uses these settings. + +To specify group configurations, you modify the value for the +``user_partitions`` policy key. + +.. note:: + ``user_partitions`` is the internal edX Platform name for group + configurations. + +The value for ``user_partitions`` is a JSON collection of group configurations, +each of which defines the groups of students. + +.. note:: + Use names for group configurations that are meaningful. You select from the + list of group configuration names when you add a content experiment. + +See the following examples for more information. + +============================================= +Example: One Group Configuration +============================================= + +The following is an example JSON object that defines an group configuration +with two student segments. + +.. code-block:: json + + "user_partitions": [{"id": 0, + "name": "Name of the group configuration", + "description": "Description of the group configuration.", + "version": 1, + "groups": [{"id": 0, + "name": "Group 1", + "version": 1}, + {"id": 1, + "name": "Group 2", + "version": 1}] + } + ] + +In this example: + +* The ``"id": 0`` identifies the group configuration. For XML courses, the + value is referenced in the ``user_partition`` attribute of the + ```` element in the content experiment file. +* The ``groups`` array identifies the groups to which students are randomly + assigned. For XML courses, each group ``id`` value is referenced in the + ``group_id_to_child`` attribute of the ```` element. + +========================================================== +Example: Multiple Group Configurations +========================================================== + +The following is an example JSON object that defines two group configurations. +The first group configuration divides students into two groups, and the second +divides students into three groups. + +.. code-block:: json + + "user_partitions": [{"id": 0, + "name": "Name of Group Configuration 1", + "description": "Description of Group Configuration 1.", + "version": 1, + "groups": [{"id": 0, + "name": "Group 1", + "version": 1}, + {"id": 1, + "name": "Group 2", + "version": 1}]} + {"id": 1, + "name": "Name of Group Configuration 2", + "description": "Description of Group Configuration 2.", + "version": 1, + "groups": [{"id": 0, + "name": "Group 1", + "version": 1}, + {"id": 1, + "name": "Group 2", + "version": 1} + {"id": 2, + "name": "Group 3", + "version": 1} + ]} + ] + +.. note:: + As this example shows, each group configuration is independent. Group IDs + and names must be unique within a group configuration, but not across all + group configurations in your course. \ No newline at end of file diff --git a/docs/en_us/course_authors/source/content_experiments/content_experiments_overview.rst b/docs/en_us/course_authors/source/content_experiments/content_experiments_overview.rst new file mode 100644 index 0000000000..59b1d62b74 --- /dev/null +++ b/docs/en_us/course_authors/source/content_experiments/content_experiments_overview.rst @@ -0,0 +1,50 @@ +.. _Overview of Content Experiments: + +################################# +Overview of Content Experiments +################################# + +You use content experiments to show different course content to different +groups of students. + +Also known as A/B or split tests, content experiments enable you to +research and compare the performance of students in different groups to gain +insight into the relative effectiveness of your course content. + +.. caution:: + If you have graded problems within a content experiment, grade exports do not + work for your course. This issue is currently being addressed. + +For more information, see: + +* :ref:`Configure Your Course for Content Experiments` +* :ref:`Add Content Experiments to Your Course` +* :ref:`Test Content Experiments` + +.. _Courses with Multiple Content Experiments: + +****************************************** +Courses with Multiple Content Experiments +****************************************** + +You can run multiple content experiments in your course. You can set up each +experiment to use the same groups of students, or you can set up each +experiment to be independent and use a different grouping. + +.. important:: + + If your course has multiple experiments, it is critical that you decide + up front if the experiments share the same groups of students or if each + experiment has its own unique grouping. If two experiments share the same + grouping, then any student that is in Group A for the first experiment will + also be in Group A for the second one. If you want the experiments to be + independent, then the experiments must use different groupings so that + students are randomly assigned for each experiment. + +To determine the available groupings of students, you :ref:`set up group +configurations in Studio ` or +:ref:`in XML `. + +You then select which grouping to use when you :ref:`add a content experiment +in Studio ` or :ref:`in XML `. \ No newline at end of file diff --git a/docs/en_us/course_authors/source/content_experiments/content_experiments_view.rst b/docs/en_us/course_authors/source/content_experiments/content_experiments_view.rst new file mode 100644 index 0000000000..e02951db46 --- /dev/null +++ b/docs/en_us/course_authors/source/content_experiments/content_experiments_view.rst @@ -0,0 +1,30 @@ +.. _Test Content Experiments: + +########################################## +Test Content Experiments +########################################## + +You should test content experiments in your course before the course starts to +ensure that content is delivered to groups as you intended. + +When you view a unit that contains a content experiment in the LMS in the Staff +view, you select one of the groups from a drop-down list. The unit page then shows the +content for that group of students. + +For example, in the following page, Group 0 is selected, and the HTML component +and video that is part of Group 0 is displayed: + +.. image:: ../Images/a-b-test-lms-group-0.png + :alt: Image of a unit page with Group 0 selected + +You can change the group selection to view the problem that a different group of +students sees: + +.. image:: ../Images/a-b-test-lms-group-2.png + :alt: Image of a unit page with Group 1 selected + +.. note:: + The example course content in this chapter uses content experiment + terminology to make the functionality clear. Typically, you would not use + terminology in course content that would make students aware of the + experiment. \ No newline at end of file diff --git a/docs/en_us/course_authors/source/content_experiments/index.rst b/docs/en_us/course_authors/source/content_experiments/index.rst new file mode 100644 index 0000000000..1f8d8fc35e --- /dev/null +++ b/docs/en_us/course_authors/source/content_experiments/index.rst @@ -0,0 +1,14 @@ +.. _Creating Content Experiments: + +############################# +Creating Content Experiments +############################# + + +.. toctree:: + :maxdepth: 2 + + content_experiments_overview + content_experiments_configure + content_experiments_add + content_experiments_view \ No newline at end of file diff --git a/docs/en_us/course_authors/source/creating_content/index.rst b/docs/en_us/course_authors/source/creating_content/index.rst index 83d369413f..6a3cafea0b 100644 --- a/docs/en_us/course_authors/source/creating_content/index.rst +++ b/docs/en_us/course_authors/source/creating_content/index.rst @@ -20,4 +20,3 @@ Index`. create_video create_discussion create_problem - diff --git a/docs/en_us/course_authors/source/developing_course/course_components.rst b/docs/en_us/course_authors/source/developing_course/course_components.rst index b1ba651707..f0f216aa8e 100644 --- a/docs/en_us/course_authors/source/developing_course/course_components.rst +++ b/docs/en_us/course_authors/source/developing_course/course_components.rst @@ -11,6 +11,7 @@ This chapter describes how you develop course components. See: * `Edit a Component`_ * `Duplicate a Component`_ * `Delete a Component`_ +* `Components that Contain Other Components`_ For more information about specific component types, see: @@ -125,13 +126,15 @@ Then follow instructions for the type of component you are editing. After you duplicate a component, the new component is not visible to students until you :ref:`publish the unit`. +.. note:: You cannot duplicate a content experiment. + .. _Delete a Component: ********************** Delete a Component ********************** -.. note:: +.. caution:: Be sure you want to delete the component. You can not undo the deletion. To delete a component: @@ -144,4 +147,187 @@ To delete a component: 2. When you receive the confirmation prompt, click **Yes, delete this component**. -After you delete a component, the component remians visible to students until you :ref:`publish the unit`. \ No newline at end of file +After you delete a component, the component remians visible to students until you :ref:`publish the unit`. + +.. _Components that Contain Other Components: + +****************************************** +Components that Contain Other Components +****************************************** + +For specific use cases, you configure course content so that components contain +other components. For example, if you want to include conditional components +or content experiments, you have to create components inside components. See +:ref:`Creating Content Experiments` for more information. + +The component that contains other components is referred to as the *parent*; +the contained components are referred to as *children*. + +In the unit page, a parent component appears with the display name and a +**View** link. For example: + +.. image:: ../Images/component_container.png + :alt: Image of a unit page with a parent component + + +================================================== +Edit a Parent Component +================================================== + +A parent component does not directly contain content. Content such as HTML, +videos, or problems are in the child components. + +A parent component has a display name. When the unit is private or in draft, +click **Edit** in the parent component to change the display name. + +.. note:: + Parent components of a specific type, such as content experiments, have + additional attributes that you edit. + + +====================================== +View Child Components +====================================== + +When you click **View** in the parent component, the parent component page +opens, showing all child components. In this example, Child Component A +contains an HTML component and a video: + +.. image:: ../Images/child-components-a.png + :alt: Image of an expanded child component + +Click the arrow next to a child component name to collapse it and hide the +component's contents: + +.. image:: ../Images/child-components.png + :alt: Image of a child component page + +Click the arrow again to expand the component. + +See: + +* `Edit a Component`_ +* `Set the Display Name for a Component`_ +* `Duplicate a Component`_ +* `Delete a Component`_ + +====================================== +Add a Child Component +====================================== + +If the containing unit is private or in draft, you can add a child component in +its parent component. + +To add a child component, open and expand the parent component. Then click the +component type that you want under **Add New Component** within the parent +component. + +.. image:: ../Images/AddNewComponent.png + :alt: Image of adding a new component + +For more information, see the documentation for the specific component type that +you want: + +- :ref:`Working with Discussion Components` +- :ref:`Working with HTML Components` +- :ref:`Working with Problem Components` +- :ref:`Working with Video Components` + + +====================================== +XML for Parent and Child Components +====================================== + +You develop parent and child components in XML, then import the XML course into +Studio to verify that the structure is as you intended. + +For more information about working with your course's XML files, including +information about terminology, see the `edX XML Tutorial `_. + +The following examples show the XML used to create the unit and components +shown in Studio above. + +The XML for the unit is: + +.. code-block:: xml + + + + + + +The ```` element above +references the parent component file that contains the child components: + +.. code-block:: xml + + + + + + +The two verticals referenced by the parent component refer to the child +components, which contain the actual content of your course: + +.. code-block:: xml + + + + + +.. code-block:: xml + + + + + + +Theoretically, there is no limit to the levels of component nesting you can use +in your course. + + +====================================== +The Student View of Nested Components +====================================== + +For students, all parent and child components are displayed on the unit page. +The following example shows the student view of the unit described above: + +.. image:: ../Images/nested_components_student_view.png + :alt: Image of the student's view of nested components + +.. note:: + The visibility of nested components depends on the visibility of the + parent unit. The parent unit must be public for students to see nested + components. For more information, see :ref:`Visibility of Components + Contained by Other Components`. + + + +******************************* +Reorganizing Child Components +******************************* + +You can reorganize child components through the same drag and drop process you +use for other objects in your course outline. You hover over the element handle +on the right side of the screen until the mouse pointer changes to a four- +headed arrow. Then, click and drag the element to the location that you want. + +Furthermore, when you have multiple levels of nesting, you can drag a child +component into a different parent component, if both parents are expanded. For +example, you can select the video component that is in Child Component A and +drag it into Child Component B. Select the video component, and as you drag it +into Child Component B, release the mouse button when a dashed outline of the +component you are moving appears in the new location: + +.. image:: ../Images/drag_child_component.png + :alt: Image of dragging a child component to a new location + +You can also drag a child component outside of a parent, so that the child +moves to the same level as the parent. + +.. note:: + For content experiments, you cannot drag a child component outside of a test + group. \ No newline at end of file diff --git a/docs/en_us/course_authors/source/index.rst b/docs/en_us/course_authors/source/index.rst index 401aeabaa2..a4111bb2e1 100755 --- a/docs/en_us/course_authors/source/index.rst +++ b/docs/en_us/course_authors/source/index.rst @@ -19,6 +19,7 @@ Building and Running an edX Course developing_course/index creating_content/index exercises_tools/index + content_experiments/index releasing_course/index running_course/index students/index