Merge pull request #2644 from edx/sylvia/documentation/BLD-842

Sylvia/documentation/bld 842

docs/en_us/course_authors/source/additional_tools.rst

@@ -111,7 +111,7 @@ Chemical Equation Problem Code
   \( \text{H}_2\text{SO}_4 \longrightarrow \text { H}^+ + \text{ HSO}_4^-\)
 
     <customresponse>
-      <chemicalequationinput size="50"/>
+      <chemicalequationinput size="50" label="Enter the chemical equation"/>
       <answer type="loncapa/python">
 
   if chemcalc.chemical_equations_equal(submission[0], 'H2SO4 -> H^+ + HSO4^-'):

docs/en_us/course_authors/source/advanced_problems.rst

@@ -34,6 +34,8 @@ These problems are easy to access in Studio. To create them, click
 **Problem** under **Add New Component**, click the **Advanced** tab, and
 then click the name of the problem that you want to create.
 
+To add a label for an advanced problem, you'll add a **label** attribute to one of the XML tags for the problem. For more information, see :ref:`Appendix E`.
+
 .. _Circuit Schematic Builder:
 
 
@@ -139,8 +141,6 @@ file that you'll download.
 #. In the problem component editor, replace the example code with the code below.
 #. Click **Save.**
 
-
-
 JavaScript Input Problem Code
 #############################
 
@@ -183,25 +183,17 @@ JavaScript Input Problem Code
 
 .. note::    When you create this problem, keep the following in mind.
 
-             - The webGLDemo.js file defines the three JavaScript functions (**WebGLDemo.getGrade**,
-               **WebGLDemo.getState**, and **WebGLDemo.setState**).
+             - The webGLDemo.js file defines the three JavaScript functions (**WebGLDemo.getGrade**, **WebGLDemo.getState**, and **WebGLDemo.setState**).
 
-             - The JavaScript input problem code uses **WebGLDemo.getGrade**, **WebGLDemo.getState**,
-               and **WebGLDemo.setState** to grade, save, or restore a problem. These functions must
-               be global in scope.
+             - The JavaScript input problem code uses **WebGLDemo.getGrade**, **WebGLDemo.getState**, and **WebGLDemo.setState** to grade, save, or restore a problem. These functions must be global in scope.
 
-             - **WebGLDemo.getState** and **WebGLDemo.setState** are optional. You only have to define
-               these functions if you want to conserve the state of the problem.
+             - **WebGLDemo.getState** and **WebGLDemo.setState** are optional. You only have to define these functions if you want to conserve the state of the problem.
 
-             - **Width** and **height** represent the dimensions of the IFrame that holds the
-               application.
+             - **Width** and **height** represent the dimensions of the IFrame that holds the application.
 
-             - When the problem opens, the cone and the cube are both blue, or "unselected." When
-               you click either shape once, the shape becomes yellow, or "selected." To unselect
-               the shape, click it again. Continue clicking the shape to select and unselect it.
+             - When the problem opens, the cone and the cube are both blue, or "unselected." When you click either shape once, the shape becomes yellow, or "selected." To unselect the shape, click it again. Continue clicking the shape to select and unselect it.
 
-             - The response is graded as correct if the cone is selected (yellow) when the user
-               clicks **Check**.
+             - The response is graded as correct if the cone is selected (yellow) when the user clicks **Check**.
 
              - Clicking **Check** or **Save** registers the problem's current state.
 

docs/en_us/course_authors/source/common_problems.rst

@@ -30,6 +30,8 @@ Types** tab, and then click the name of the problem. (Note that
 **Checkbox** doesn't appear in the list of common problem types. To
 create a checkbox problem, you'll click **Blank Common Problem**.)
 
+To add labels to these problems, enclose the text that you want to use as a label in two sets of angle brackets (<<>>).
+
 .. _Checkbox:
 
 *******************
@@ -53,6 +55,7 @@ Create a Checkbox Problem
 #. In the Problem component that appears, click **Edit**.
 #. In the component editor, replace the default text with the text of your 
    problem. Enter each answer option on its own line.
+#. Determine the text of the problem to use as a label, and then surround that text with two sets of angle brackets (<<>>).
 #. Select all the answer options, and then click the checkbox button. 
 
    .. image:: Images/ProbComponent_CheckboxIcon.gif
@@ -76,7 +79,7 @@ following.
 ::
 
     Learning about the benefits of preventative healthcare can be particularly 
-    difficult. Check all of the reasons below why this may be the case.
+    difficult. >>Check all of the reasons below why this may be the case.<<
 
     [x] A large amount of time passes between undertaking a preventative measure 
     and seeing the result. 
@@ -122,6 +125,7 @@ To create a dropdown problem, follow these steps.
 #. In the new Problem component that appears, click **Edit**.
 #. Replace the default text with the text for your problem. Enter each of the possible 
    answers on the same line, separated by commas.
+#. Determine the text of the problem to use as a label, and then surround that text with two sets of angle brackets (<<>>).
 #. Select all the answer options, and then click the dropdown button. 
       
    .. image:: Images/ProbCompButton_Dropdown.gif
@@ -145,7 +149,7 @@ following.
 
 ::
 
-    What type of data are the following?
+    >>What type of data are the following?<<
 
     Age:
     [[Nominal, Discrete, (Continuous)]]
@@ -180,6 +184,7 @@ Create a Multiple Choice Problem
 #. When the new Problem component appears, click **Edit**.
 #. In the component editor, replace the sample problem text with the text of your 
    problem. Enter each answer option on its own line.
+#. Determine the text of the problem to use as a label, and then surround that text with two sets of angle brackets (<<>>).
 #. Select all the answer options, and then click the multiple choice button. 
    
    .. image:: Images/ProbCompButton_MultChoice.gif
@@ -204,7 +209,7 @@ following.
 
 ::
 
-    Lateral inhibition, as was first discovered in the horsehoe crab:
+    >>Lateral inhibition, as was first discovered in the horsehoe crab:<<
 
     ( ) is a property of touch sensation, referring to the ability of crabs to 
     detect nearby predators.
@@ -261,7 +266,7 @@ Create a Numerical Input Problem
    Input** on the **Common Problem Types** tab.
 #. When the new Problem component appears, click **Edit**.
 #. In the component editor, replace the sample problem text with your own text.
-
+#. Determine the text of the problem to use as a label, and then surround that text with two sets of angle brackets (<<>>).
 #. Select the text of the answer, and then click the numerical input button. 
 
    .. image:: Images/ProbCompButton_NumInput.gif
@@ -291,7 +296,7 @@ following.
 
 ::
 
-   How many different countries do edX students live in as of May 2013?
+   >>How many different countries do edX students live in as of May 2013?<<
 
    = 193 +- 5%
     
@@ -343,6 +348,7 @@ To create a text input problem, follow these steps.
    on the **Common Problem Types** tab.
 #. In the new Problem component that appears, click **Edit**.
 #. Replace the default text with the text for your problem.
+#. Determine the text of the problem to use as a label, and then surround that text with two sets of angle brackets (<<>>).
 #. Select the text of the answer, and then click the text input button. 
    
    .. image:: Images/ProbCompButton_TextInput.gif
@@ -365,8 +371,8 @@ following.
 
 ::
 
-    What is the technical term that refers to the fact that, when enough people 
-    sleep under a bednet, the disease may altogether disappear?
+    >>What is the technical term that refers to the fact that, when enough people 
+    sleep under a bednet, the disease may altogether disappear?<<
     = herd immunity
 
     [explanation]

docs/en_us/course_authors/source/create_problem_component.rst

@@ -107,16 +107,17 @@ All problems on the edX platform have several component parts.
 .. note::  Problems can be **open** or **closed.** Closed problems do not
            have a **Check** button. Students can still see questions, solutions,
            and revealed explanations, but they cannot check their work, submit
-           responses, or change their stored score.
+           responses, or change an earlier score.
 
 There are also some attributes of problems that are not immediately
-visible.
+visible. You can set these attributes in Studio.
 
 -  **Randomization.** For some problems, the instructor can specify
    whether a problem will use randomly generated numbers that vary from
    student to student.
 -  **Weight.** Different problems in a particular problem set may be
    given different weights.
+-  **Label.** To improve accessibility for students who have disabilities, each problem needs a descriptive label. The label typically contains part or all of the text of the question in the problem. Most templates include a space for a label. You can find example labels in the documentation for each problem or tool type. 
 
 .. _Studio UI:
 
@@ -158,7 +159,7 @@ the text for you automatically. The toolbar buttons are the following:
 
 The following image shows a multiple choice problem in the Simple Editor.
 
-.. image:: Images/MultipleChoice_SimpleEditor.gif
+.. image:: Images/MultipleChoice_SimpleEditor.png
  :alt: Image of a problem in the simple editor
 
 .. _Advanced Editor:
@@ -173,7 +174,7 @@ For more information about the XML for different problem types, see :ref:`Append
 The following image shows the multiple choice problem above in the Advanced Editor
 instead of the Simple Editor.
 
-.. image:: Images/MultipleChoice_AdvancedEditor.gif
+.. image:: Images/MultipleChoice_AdvancedEditor.png
  :alt: Image of a problem in the advanced editor
 
 .. _Problem Settings:
@@ -182,19 +183,17 @@ instead of the Simple Editor.
 Problem Settings
 ******************
 
-All problems except word cloud and open response assessment problems
-have the following settings. These settings appear on the **Settings** tab in
-the component editor. (The settings for open response assessments and word clouds
-are listed on the page for those problem types.)
+Most problems have the following settings. These settings appear on the **Settings** tab in
+the component editor. 
 
--  Display Name
--  Maximum Attempts
--  Problem Weight
--  Randomization
--  Show Answer
+-  **Display Name**
+-  **Maximum Attempts**
+-  **Problem Weight**
+-  **Randomization**
+-  **Show Answer**
 
-.. image:: Images/ProbComponent_Attributes.gif
- :alt: Image of the problem settings dialog box
+.. image:: Images/ProbComponent_Attributes.png
+ :alt: Image of the Settings tab in a Problem component
 
 ===============
 Display Name