Merge pull request #463 from jswope00/jswope00/migrating_legacy_docs_…

…to_wip

Migrate Legacy Educator docs to an Orphan page

.gitignore

@@ -2,3 +2,4 @@ build
 .DS_Store
 source/.DS_Store
 .idea/
+sphinx-env/

source/conf.py

@@ -124,6 +124,7 @@
     "default_image_width": "60%",
 }
 
+# 'migration_wip' links.rst added while migration is underway. Should be removed after migration. 
 rst_epilog = """
 
 .. raw:: html
@@ -136,6 +137,7 @@
 
 .. include:: /substitutions.txt
 .. include:: /links.txt
+.. include:: /educators/migration_wip/links/links.rst
 
 """
 

source/educators/migration_wip/10_exercises_tools/Section_adding_hints.rst

@@ -0,0 +1,139 @@
+.. _Adding Feedback and Hints to a Problem:
+
+=======================================
+Adding Feedback and Hints to a Problem
+=======================================
+
+You can add feedback, hints, or both to the simple problem types.
+
+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 displays to learners after they submit an answer.
+
+For example, the following single select problem provides feedback in
+response to the selected option when the learner selects **Submit**. In this
+case, feedback is given for an incorrect answer.
+
+.. image:: ../images/multiple_choice_feedback.png
+ :alt: Image of a single select 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 single select and dropdown problems, the feedback should provide a
+reason why the selection is correct.
+
+------------------------------------------
+Providing Hints for Problems
+------------------------------------------
+
+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 single select problem, the learner selects
+**Hint** after having made one incorrect attempt.
+
+.. image:: ../images/multiple_choice_hint.png
+ :alt: Image of a single select problem with the first hint.
+ :width: 600
+
+The hint text indicates that it is the first of two hints. After the learner
+selects **Next Hint**, both of the available hints appear. When all hints have
+been used, the **Hint** or **Next Hint** option is no longer available.
+
+.. image:: ../images/multiple_choice_hint2.png
+ :alt: Image of a single select 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
+------------------------------------------
+
+While editing a problem block, you can apply **Answer-specific feedback**
+for all problem types. **Group feedback** can only be applied to 
+**multi-select** problems.
+
+Any number of **hints** can be added for all simple problem types.
+
+------------------------------------------
+Adding Answer-specific Feedback
+------------------------------------------
+
+**Answer-specific feedback** can be added under each answer by pressing
+the feedback icon to the right of the answer text. Feedback entered in
+these fields are given when the learner selects that answer or when the
+learner does not select that answer.
+
+.. image:: ../images/problem_editor_feedback_box.png
+ :alt: Image of the answer-specific feedback settings.
+ :width: 600
+
+.. note::
+   The “is not selected” feedback field shown above is only available
+   for the **multi-select** problem type.
+
+------------------------------------------------
+Adding Group Feedback for Multi-Select Problems
+------------------------------------------------
+
+This setting can be found on the collapsible settings to the right of
+the problem editor. Feedback entered in this field will display if and
+only if the learner selects all of the checked answers. Click the 
+**Add group feedback** button to add additional feedback for different
+groups of checked answers. **Group feedback** can only be applied for
+the **multi-select** problem type.
+
+.. image:: ../images/problem_editor_group_feedback_box.png
+ :alt: Image of the group feedback settings.
+ :width: 300
+
+------------------------------------------
+Adding Hints
+------------------------------------------
+
+This setting can be found on the collapsible settings to the right of
+the problem editor. Click the **Add hint** button to add additional
+hints for learners.
+
+.. image:: ../images/problem_editor_hints_box.png
+ :alt: Image of the hints settings.
+ :width: 300

source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints.rst

@@ -0,0 +1,12 @@
+In the settings panels on the right of the editor, you'll find a Hints panel.
+
+.. image:: ../images/problem_editor_hints_box.png
+ :alt: An example of the hints settings panel.
+ :width: 200
+
+Click the **Add hint** button to add a new hint text field. To delete any hints
+you've added, click the trash can icon next to its respective hint field.
+
+.. 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.

source/educators/migration_wip/10_exercises_tools/Subsection_configure_hints_advanced.rst

@@ -0,0 +1,33 @@
+
+In the advanced editor, you add the ``<demandhint>`` element immediately before
+the closing ``</problem>`` tag, and then configure each hint using the
+``<hint>`` element.
+
+.. code-block:: xml
+
+  <problem>
+  .
+  .
+  .
+  <demandhint>
+    <hint>Hint 1</hint>
+    <hint>Hint 2</hint>
+    <hint>Hint 3</hint>
+  </demandhint>
+  </problem>
+
+For example, the following OLX for a single select problem shows two hints.
+
+.. code-block:: xml
+
+  <problem>
+    <multiplechoiceresponse>
+    .
+    .
+    .
+    </multiplechoiceresponse>
+    <demandhint>
+      <hint>A fruit is the fertilized ovary from a flower.</hint>
+      <hint>A fruit contains seeds of the plant.</hint>
+    </demandhint>
+  </problem>

source/educators/migration_wip/10_exercises_tools/Subsection_customizing_feedback_labels.rst

@@ -0,0 +1,47 @@
+-----------------------------
+Customizing Feedback Labels
+-----------------------------
+
+By default, the feedback labels shown to learners are **Correct** and
+**Incorrect**. If you do not define feedback labels, learners see these terms
+when they submit an answer, as in the following example.
+
+::
+
+  Incorrect: A pumpkin is the fertilized ovary of a squash plant and contains
+  seeds classifying it as a fruit.
+
+You can configure the problem to override the default labels. For example, you
+can configure a custom label for a specific wrong answer.
+
+::
+
+  Not Quite: Many people mistakenly think a tomato is a vegetable. However,
+  because a tomato is the fertilized ovary of a tomato plant and contains seeds
+  it is classified as a fruit.
+
+In the :ref:`advanced editor<Advanced Editor>`, you configure custom feedback
+labels with the following syntax.
+
+.. code-block:: xml
+
+  <choice correct="true or false">Answer
+    <choicehint label="Custom Label">Feedback for learners who select this
+    answer.</choicehint>
+  </choice>
+
+For example, the feedback for the following answer option is configured to use
+a custom label.
+
+.. code-block:: xml
+
+  <choice correct="false">tomato
+    <choicehint label="Not Quite">Many people mistakenly think a tomato is a
+    vegetable. However, because a tomato is the fertilized ovary of a tomato
+    plant and contains seeds, it is a fruit.</choicehint>
+  </choice>
+
+.. note::
+  The default labels **Correct** and **Incorrect** display in the learner's
+  requested language. If you provide custom labels, they display as you define
+  them to all learners. They are not translated into different languages.

source/educators/migration_wip/10_exercises_tools/annotation.rst

@@ -0,0 +1,94 @@
+.. _Annotation:
+
+###################
+Annotation Problem
+###################
+
+.. note:: EdX does not support this problem type.
+
+In an annotation problem, you highlight specific text inside a larger text
+block and then ask questions about that text. The questions appear when
+learners move their cursors over the highlighted text. The questions also
+appear in a section below the text block, along with space for learners'
+responses.
+
+.. image:: ../images/AnnotationExample.png
+  :alt: An example annotation problem.
+
+.. contents::
+  :local:
+  :depth: 1
+
+*****************************
+Enable Annotation Problems
+*****************************
+
+Before you can add annotation problems to your course, you must enable
+annotation problems in Studio.
+
+To enable annotation problems in Studio, you add the ``"annotatable"`` key to
+the **Advanced Module List** on the **Advanced Settings** page. (Be sure to
+include the quotation marks around the key value.) For more information, see
+:ref:`Enable Additional Exercises and Tools`.
+
+****************************
+Create an Annotation Problem
+****************************
+
+To create an annotation problem, you add the **Instructions** and **Guided
+Discussion** segments of the problem, and then the **Annotation problem**
+segment of the problem.
+
+============================================
+Add Instructions and Guided Discussion
+============================================
+
+To add the **Instructions** and **Guided Discussion** segments of the problem,
+follow these steps.
+
+#. In the unit where you want to create the problem, under **Add New
+   Component** select **Advanced**.
+
+#. In the list of problem types, select **Annotation**.
+
+#. In the component that appears, select **Edit**.
+
+#. In the component editor, replace the example code with your own code.
+
+#. Select **Save**.
+
+=================================
+Add Annotation Problem
+=================================
+
+To add the **Annotation problem** segment of the problem, follow these steps.
+
+#. Under the annotation component, create a new blank advanced problem
+   component.
+
+#. Paste the following code in the advanced problem component, replacing
+   placeholders with your own information.
+
+   .. code-block:: xml
+
+       <problem>
+           <annotationresponse>
+               <annotationinput>
+                 <text>PLACEHOLDER: Text of annotation</text>
+                   <comment>PLACEHOLDER: Text of question</comment>
+                   <comment_prompt>PLACEHOLDER: Type your response below:</comment_prompt>
+                   <tag_prompt>PLACEHOLDER: In your response to this question, which tag below do you choose?</tag_prompt>
+                 <options>
+                   <option choice="incorrect">PLACEHOLDER: Incorrect answer (to make this option a correct or partially correct answer, change choice="incorrect" to choice="correct" or choice="partially-correct")</option>
+                   <option choice="correct">PLACEHOLDER: Correct answer (to make this option an incorrect or partially correct answer, change choice="correct" to choice="incorrect" or choice="partially-correct")</option>
+                   <option choice="partially-correct">PLACEHOLDER: Partially correct answer (to make this option a correct or partially correct answer, change choice="partially-correct" to choice="correct" or choice="incorrect")
+                   </option>
+                 </options>
+               </annotationinput>
+           </annotationresponse>
+           <solution>
+             <p>PLACEHOLDER: Detailed explanation of solution</p>
+           </solution>
+         </problem>
+
+#. Select **Save**.