Merge pull request #361 from edx/markhoeber-doc1645

WIP: Extended Hints - Course Staff doc

en_us/course_authors/source/front_matter/change_log.rst

@@ -2,6 +2,33 @@
 Change Log
 ############
 
+****************
+July 2015
+****************
+
+.. list-table::
+   :widths: 15 70
+   :header-rows: 1
+
+   * - Date
+     - Change
+   * - 01 July
+     - Several additions were made to provide information about using feedback
+       and hints in common problems.
+
+       * :ref:`Adding Feedback and Hints to a Problem`
+
+       * :ref:`Use Feedback in a Checkbox Problem`
+       * :ref:`Use Hints in a Checkbox Problem`
+       * :ref:`Use Feedback in a Dropdown Problem` 
+       * :ref:`Use Hints in a Dropdown Problem`
+       * :ref:`Use Feedback in a Multiple Choice Problem` 
+       * :ref:`Use Hints in a Multiple Choice Problem`
+       * :ref:`Use Feedback in a Numerical Input Problems` 
+       * :ref:`Use Hints in a Numerical Input Problem`
+       * :ref:`Use Feedback in a Text Input Problem` 
+       * :ref:`Use Hints in a Text Input Problem`
+
 ****************
 June 2015
 ****************

en_us/olx/source/front_matter/change_log.rst

@@ -2,6 +2,33 @@
 Change Log
 ############
 
+****************
+March 2015
+****************
+
+.. list-table::
+   :widths: 10 70
+   :header-rows: 1
+
+   * - Date
+     - Change
+   * - 23 June
+     - Several additions were made to provide information about using feedback
+       and hints in common problems.
+
+       * :ref:`Adding Feedback and Hints to a Problem`
+       * :ref:`Use Feedback in a Checkbox Problem`
+       * :ref:`Use Hints in a Checkbox Problem`
+       * :ref:`Use Feedback in a Dropdown Problem` 
+       * :ref:`Use Hints in a Dropdown Problem`
+       * :ref:`Use Feedback in a Multiple Choice Problem` 
+       * :ref:`Use Hints in a Multiple Choice Problem`
+       * :ref:`Use Feedback in a Numerical Input Problems` 
+       * :ref:`Use Hints in a Numerical Input Problem`
+       * :ref:`Use Feedback in a Text Input Problem` 
+       * :ref:`Use Hints in a Text Input Problem`
+
+
 ****************
 March 2015
 ****************

en_us/olx/source/problem-xml/create_problem.rst

@@ -422,6 +422,8 @@ element:
   
   <problem show_reset_button="true"  . . . >
 
+.. include:: ../../../shared/exercises_tools/Section_adding_hints.rst
+
 .. _Modifying a Released Problem:
 
 *********************************
@@ -573,6 +575,6 @@ Create Randomized Problems
          </randomize>
        </vertical>
 
-.. include:: ../../../shared/exercises_tools/adding_tooltip.rst
+.. include:: ../../../shared/exercises_tools/Section_adding_tooltip.rst       
 
 .. include:: ../links.rst

en_us/open_edx_course_authors/source/front_matter/change_log.rst

@@ -2,6 +2,34 @@
 Change Log
 ############
 
+****************
+July 2015
+****************
+
+.. list-table::
+   :widths: 15 70
+   :header-rows: 1
+
+   * - Date
+     - Change
+   * - 01 July
+     - Several additions were made to provide information about using feedback
+       and hints in common problems.
+
+       * :ref:`Adding Feedback and Hints to a Problem`
+
+       * :ref:`Use Feedback in a Checkbox Problem`
+       * :ref:`Use Hints in a Checkbox Problem`
+       * :ref:`Use Feedback in a Dropdown Problem` 
+       * :ref:`Use Hints in a Dropdown Problem`
+       * :ref:`Use Feedback in a Multiple Choice Problem` 
+       * :ref:`Use Hints in a Multiple Choice Problem`
+       * :ref:`Use Feedback in a Numerical Input Problems` 
+       * :ref:`Use Hints in a Numerical Input Problem`
+       * :ref:`Use Feedback in a Text Input Problem` 
+       * :ref:`Use Hints in a Text Input Problem`
+
+
 *****************
 Apr-Jun 2015
 *****************

en_us/shared/building_and_running_chapters/creating_content/create_problem.rst

@@ -33,7 +33,7 @@ To have problems to count toward the grade, change the assignment type of the
 subsection that contains the problems. For more information, see :ref:`Set the
 Assignment Type and Due Date for a Subsection`.
 
-.. _Problem Student View:
+.. _Problem Learner View:
 
 ************************************
 The Learner View of a Problem
@@ -187,7 +187,8 @@ preformatted example problem.
 *  :ref:`Text Input`: In text input problems, learners enter a short text
    answer to a question.
 
-The following image shows an example multiple choice problem in the Simple Editor.
+The following image shows an example multiple choice problem in the Simple
+Editor.
 
 .. image:: ../../../shared/building_and_running_chapters/Images//MultipleChoice_SimpleEditor.png
  :alt: An image of the simple editor with numbered callouts for options and an 
@@ -600,21 +601,11 @@ ask your learners to go back and resubmit answers to a problem.
 For information about how to review and adjust learner grades in the LMS, see
 :ref:`Grades`.
 
-.. _Additional Work with Problems:
-
-************************************
-Additional Work with Problems
-************************************
-
-You have some further options when you work with problems. You can include more
-than one problem in a single problem component, or you can set up a problem
-that presents different versions to different learners.
-
 .. _Multiple Problems in One Component:
 
-====================================
+***********************************
 Multiple Problems in One Component
-====================================
+***********************************
 
 You might want to create a problem that has more than one response type. For
 example, you might want to create a numerical input problem and then include a
@@ -643,11 +634,13 @@ individually. If a learner selects **Check**, the LMS scores all of the
 problems in the component at once. If a learner selects **Show Answer**, the
 answers for all the problems in the component appear.
 
+.. include:: ../../../shared/exercises_tools/Section_adding_hints.rst
+
 .. _Problem Randomization:
 
-===========================
+***********************************
 Problem Randomization
-===========================
+***********************************
 
 You might want to present different learners with different problems, or
 different versions of the same problem. To do this, you create a problem
@@ -665,8 +658,9 @@ versions to different learners.
  your course before you do this. We also recommend that you only edit your
  course files in the text editor if you are very familiar with editing XML.
 
+============
 Terminology
-************
+============
 
 Sections, subsections, units, and components have different names in the
 **Course Outline** view and in the list of files that you'll see after you
@@ -695,8 +689,9 @@ contains. To find a unit, look in the **Vertical** directory.
 
 .. _Create Randomized Problems:
 
+==========================
 Create Randomized Problems
-****************************
+==========================
 
 #. In the unit where you want to create a randomized problem, create a separate
    problem component for each version or problem that you want to randomize.
@@ -771,6 +766,6 @@ Create Randomized Problems
   * A .csv file for learner responses contains the responses to each of the
     problems in the problem bank.
 
-.. include:: ../../../shared/exercises_tools/adding_tooltip.rst
+.. include:: ../../../shared/exercises_tools/Section_adding_tooltip.rst
 
 .. _Using edX Insights: http://edx.readthedocs.org/projects/edx-insights/en/latest/

en_us/shared/exercises_tools/Section_adding_hints.rst

@@ -0,0 +1,114 @@
+.. _Adding Feedback and Hints to a Problem:
+
+***************************************
+Adding Feedback and Hints to a Problem
+***************************************
+
+You can add feedback, hints, or both to the following problem types. 
+
+* :ref:`Checkbox`
+* :ref:`Dropdown`
+* :ref:`Multiple Choice`
+* :ref:`Numerical Input`
+* :ref:`Text Input`
+
+By using hints and feedback, you can provide learners with guidance and help as
+they work on problems.
+
+==========================================
+Feedback in Response to Attempted Answers
+==========================================
+
+You can add feedback that is displayed to learners when they submit an answer. 
+
+For example, the following multiple choice problem provides feedback in
+response to the selected option when the learner selects **Check**. In this
+case, feedback is given for an incorrect answer.
+
+.. image:: ../../../shared/building_and_running_chapters/Images/multiple_choice_feedback.png
+ :alt: Image of a multiple choice problem with feedback.
+ :width: 600
+
+==========================================
+Best Practices for Providing Feedback
+==========================================
+
+The immediacy of the feedback available to learners is a key advantage of
+online instruction and difficult to do in a traditional classroom environment.
+
+You can target feedback for common incorrect answers to the misconceptions that
+are common for the level of the learner (for example, elementary, middle, high
+school, college).
+
+In addition, you can create feedback that provides some guidance to the
+learner about how to arrive at the correct answer. This is especially important
+in text input and numeric input problems, because without such guidance,
+learners might not be able to proceed.
+
+You should also include feedback for the correct answer to reinforce why the
+answer is correct. Especially in questions where learners are able to guess,
+such as multiple choice and dropdown problems, the feedback should provide a
+reason why the selection is correct.
+
+============================
+General Hints to a Problem
+============================
+
+You can add one or more hints that are displayed to learners. When you add
+hints, the **Hint** button is automatically displayed to learners. Learners can
+access the hints by selecting **Hint** beneath the problem.  A learner can view
+multiple hints by selecting **Hint** multiple times.
+
+For example, in the following multiple choice problem, the learner selects
+**Hint** before attempting the answer.
+
+.. image:: ../../../shared/building_and_running_chapters/Images/multiple_choice_hint.png
+ :alt: Image of a multiple choice problem with the first hint.
+ :width: 600
+
+The hint indicates that it is the first of two hints. The learner selects
+**Hint** a second time.
+
+.. image:: ../../../shared/building_and_running_chapters/Images/multiple_choice_hint2.png
+ :alt: Image of a multiple choice problem with the second hint.
+ :width: 600
+
+==========================================
+Best Practices for Providing Hints
+==========================================
+
+To ensure that your hints can assist learners with varying backgrounds and
+levels of understanding, you should provide multiple hints with different
+levels of detail.
+
+For example, the first hint can orient the learner to the problem and help
+those struggling to better understand what is being asked.  
+
+The second hint can then take the learner further towards the answer. 
+
+In problems that are not graded, the third and final hint can explain the
+solution for learners who are still confused.
+
+==========================================
+Create Problems with Feedback and Hints
+==========================================
+
+You create problems with feedback and hints in Studio. Templates with feedback
+and hints configured are available to make creating your own problems easier.
+
+When editing a unit, in the **Add New Component** panel, select **Problem**. In
+the list that opens, select **Common Problems with Hints and Feedback**.
+
+.. image:: ../../../shared/building_and_running_chapters/Images/hints_feedback_problem_templates.png
+ :alt: Image of a the templates with hints and feedback in Studio.
+ :width: 600
+
+Add the problem type you need to the unit, then edit the component.  The exact
+syntax you use to configure hints and feedback depends on the problem type.
+See the topic for the problem type for more information.
+
+* :ref:`Checkbox`
+* :ref:`Dropdown`
+* :ref:`Multiple Choice`
+* :ref:`Numerical Input`
+* :ref:`Text Input`

en_us/shared/exercises_tools/Subsection_configure_hints.rst

@@ -0,0 +1,46 @@
+====================================
+Configure Hints in the Simple Editor
+====================================
+
+In the simple editor, you configure hints with the following syntax.
+
+::
+
+  ||Hint 1||
+  ||Hint 2||
+  ||Hint n||
+
+.. note:: 
+  You can configure any number of hints. The learner views one hint at a time
+  and views the next one by selecting **Hint** again.
+
+For example, the following problem has two hints.
+
+::
+
+  ||A fruit is the fertilized ovary from a flower.||
+  ||A fruit contains seeds of the plant.||
+
+======================================
+Configure Hints in the Advanced Editor
+======================================
+
+In the advanced editor, you configure each hint in the ``<hint>`` element
+within the ``<demandhint>`` element.
+
+.. code-block:: xml
+
+  <demandhint>
+    <hint>Hint 1</hint>
+    <hint>Hint 2</hint>
+    <hint>Hint 3</hint>
+  </demandhint>
+
+For example, the following XML shows two hints.
+
+.. code-block:: xml
+
+  <demandhint>
+    <hint>A fruit is the fertilized ovary from a flower.</hint>
+    <hint>A fruit contains seeds of the plant.</hint>
+  </demandhint>