Merge pull request #3431 from edx/sylvia/docs/DOC-263

Update screenshots and add feedback prompt info

docs/en_us/ORA2/source/PeerAssessment.rst

@@ -35,9 +35,9 @@ When you create a peer assessment problem, you'll specify several elements:
 
 For step-by-step instructions, see :ref:`PA Create a PA Problem`.
 
-
+=======================================
 Number of Responses and Assessments
-***********************************
+=======================================
 
 In the problem code, you'll indicate the **number of responses** each student has to assess and the **number of peer assessments** each response has to receive.
 
@@ -47,20 +47,24 @@ If all responses have received assessments, but some students haven't completed
 
 For more information, see :ref:`PA Specify Name and Assessment Types`.
 
+=====================
 Assessment Type
-********************
+=====================
 
 In your problem, you'll also specify the **assessment type or types**. You can see the type and order of the assessments when you look at the problem. In the following example, after students submit a response, they complete peer assessments on other students' responses ("Assess Peers") and then complete self assessments ("Assess Yourself").
 
-.. image:: /Images/PA_Steps_LMS.png
-  :alt: Image of peer assessment with assessment types circled
+.. image:: /Images/PA_AsmtWithResponse.png
+  :alt: Image of peer assessment with assessment steps and status labeled
+  :width: 600
+
 
 .. note:: In this initial release, the type and order of assessments cannot be changed. Students must complete peer assessments followed by a self assessment.
 
 For more information, see :ref:`PA Specify Name and Assessment Types`.
 
+===================================
 Start and Due Dates (optional)
-******************************
+===================================
 
 You can specify **start dates** and **due dates** for students to submit responses, perform peer assessments, and perform self assessments.
 
@@ -72,8 +76,9 @@ If you don't specify dates, the deadline for all elements--responses, peer asses
 
 For more information, see :ref:`PA Add Due Dates`.
 
+==============
 Question
-************
+==============
 
 You'll also specify the **question** that you want your students to answer. This appears near the top of the component, followed by a field where the student enters a response.
 
@@ -83,8 +88,9 @@ For more information, see :ref:`PA Add Question`.
 
 .. _PA Rubric:
 
+=======
 Rubric
-*********
+=======
 
 Your problem must include a **rubric** that you design. The same rubric is used for peer and self assessments, and the rubric appears when students begin grading. Students compare their peers' responses to the rubric.
 
@@ -193,10 +199,11 @@ Create a Peer Assessment Problem
 
 .. warning:: Peer assessments are in limited release and are only available in a few courses. To enable the peer assessment feature in your course, contact your edX program manager. After the feature has been enabled, you can create peer assessments by following the steps below.
 
-To create a peer assessment problem, you'll edit the XML code in a Problem component, similar to creating other problems. The following image shows what a peer assessment component looks like when you edit it in Studio, as well as the way that students see that peer assessment in the LMS.
+To create a peer assessment problem, you'll edit the XML code in a Problem component, similar to creating other problems. The following image shows what a peer assessment component looks like when you edit it in Studio, as well as the way that students see that peer assessment in the courseware.
 
-.. image:: /Images/PA_All_XML-LMS_small.png
+.. image:: /Images/PA_XML_LMS_All.png
    :alt: Image of a peer assessment in Studio and LMS views
+   :width: 800
 
 Creating a peer assessment is a multi-step process:
 
@@ -211,8 +218,9 @@ Each of these steps is covered in detail below.
 
 .. _PA Create Component:
 
+============================
 Step 1. Create the Component
-****************************
+============================
 
 #. In Studio, open the unit where you want to create the assessment.
 #. Under **Add New Component**, click **Advanced**, and then click **Peer Assessment**.
@@ -224,8 +232,9 @@ Step 1. Create the Component
 
 .. _PA Specify Name and Assessment Types:
 
+========================================================
 Step 2. Specify the Problem Name and Assessment Types
-*****************************************************
+========================================================
 
 To specify problem data such as the name and assessment types, you'll work with the XML at the top of the problem.
 
@@ -257,8 +266,9 @@ To specify your problem data, follow these steps.
 
 .. _PA Add Due Dates:
 
+==========================================
 Step 3. Add Start and Due Dates (optional)
-******************************************
+==========================================
 
 .. note:: Setting start and due dates is optional. If you don't specify dates, the deadline for all student responses and assessments is the due date that you set for the subsection that contains the peer assessment. If you do specify dates, those dates take precedence over the subsection due date.
 
@@ -305,29 +315,33 @@ In this example, the problem is set at the subsection level to open on February
 
 .. _PA Add Question:
 
+============================
 Step 4. Add the Question
-********************************
+============================
 
-The following image shows a question in the component editor, followed by the way the question appears to students.
+The following image shows a question in the component editor along with the way the question appears to students.
 
 .. image:: /Images/PA_Question_XML-LMS.png
       :alt: Image of question in XML and the LMS
+      :width: 800
 
 To add the question:
 
 #. In the component editor, locate the ``<prompt>`` tags.
 
-#. Replace the sample text between the ``<prompt>`` tags with the text of your question. Note that the component editor respects paragraph breaks inside the ``<prompt>`` tags. You don't have to add ``<p>`` tags to create individual paragraphs.
+#. Replace the sample text between the ``<prompt>`` tags with the text of your question. Note that the component editor respects paragraph breaks and new lines inside the ``<prompt>`` tags. You don't have to add ``<p>`` tags to create individual paragraphs.
 
-In this initial release, you cannot add text formatting or images in the Peer Assessment component. If you want to include text formatting or images in the text of your prompt, you can add an HTML component above the Peer Assessment component. The following image shows an HTML component that contains an image and the quote by Katherine Paterson, followed by a Peer Assessment component that contains the introductory text ("This problem requires...") and the text that appears between the ``<prompt>`` tags in the Peer Assessment component ("Write a persuasive essay...").
+In this initial release, you cannot add text formatting or images in the Peer Assessment component. If you want to include text formatting or images in the text of your prompt, you can add an HTML component above the Peer Assessment component. The following image shows an HTML component that contains an image and the quote by Katherine Paterson, followed by a Peer Assessment component that contains the introductory Peer Assessment text ("This assignment has several steps...") and the text that appears between the ``<prompt>`` tags in the Peer Assessment component ("Write a persuasive essay...").
 
 .. image:: /Images/PA_HTML-PA_LMS.png
       :alt: Image of a peer assessment that has an image in an HTML component
+      :width: 500
 
 .. _PA Add Rubric:
 
+============================
 Step 5. Add the Rubric
-********************************
+============================
 
 To add the rubric, you'll create your criteria and options in XML. The following image shows a highlighted criterion and its options in the component editor, followed by the way the criterion and options appear to students.
 
@@ -396,11 +410,40 @@ You can use the following code as a template:
 	   </option>
 	 </criterion>
 
+.. _PA Change Feedback Prompt:
+
+=============================================
+Step 6 (optional). Change the Feedback Prompt
+=============================================
+
+After students have filled out the rubric, they can provide additional feedback for the responses they've assessed. By default, the prompt text for this feedback is the following:
+
+``(Optional) What aspects of this response stood out to you? What did it do well? How could it improve?``
+
+You can replace this default text with your own text.
+
+To change this text:
+
+#. Locate the ``<feedbackprompt>`` tags between the final ``</criterion>`` tag and the closing ``</rubric>`` tag:
+
+  .. code-block:: xml
+
+          <option points="3">
+            <name>Excellent</name>
+            <explanation>Includes in-depth information and exceptional supporting details that are fully developed.  Explores all facets of the topic.</explanation>
+          </option>
+        </criterion>
+        <feedbackprompt>(Optional) What aspects of this response stood out to you? What did it do well? How could it improve?</feedbackprompt>
+      </rubric>
+     </openassessment>
+
+#. Change the text between the ``<feedbackprompt>`` tags to the text that you want.
 
 .. _PA Test Problem:
 
-Step 6. Test the Problem
-********************************
+============================
+Step 7. Test the Problem
+============================
 
 To test your assignment, set up the assignment in a test course, and ask a group of beta users to submit responses and grade each other. The beta testers can then let you know if they found the question and the rubric easy to understand or if they found any problems with the assignment.
 

docs/en_us/ORA2/source/PeerAssessment_Students.rst

@@ -12,8 +12,9 @@ Student Instructions
 
 Peer assessment problems have several steps--you'll submit a response, then assess (grade) peer responses, and then assess your own response.  When you come to a peer assessment problem in the course, you'll see the question and a response field, followed by grayed-out steps that show you what you'll do next.
 
-.. image:: /Images/PA_S_QandRfield.png
-   :alt: Image of a peer assessment question and student response field
+.. image:: /Images/PA_AsmtWithResponse_Students.png
+   :alt: Peer assessment example with question, response field, and assessment types and status labeled
+   :width: 550
 
 Here, we'll walk you through the process of performing a peer assessment:
 
@@ -40,16 +41,17 @@ After you compose a response, type it into the response field under **Your Respo
 
 After you submit your response, if no other students have submitted responses yet, you'll see the following message:
 
-	Waiting for Peer Responses
+	**Waiting for Peer Responses**
 
-	All submitted peer responses have been assessed. Check back later to see if more students have submitted responses. You'll receive your grade after you complete the peer assessment and self assessment steps, and after your peers have assessed your response.
+	**All submitted peer responses have been assessed. Check back later to see if more students have submitted responses. You'll receive your grade after you complete the peer assessment and self assessment steps, and after your peers have assessed your response.**
 
 If other students have already submitted responses, the peer assessment step starts immediately after you submit your response. However, you don't have to start grading right away. If you want to stop working and come back later, just refresh or reopen your browser when you come back. New peer responses will be available for you to grade.
 
-Note that you can go back and review your response at any time after you submit it. To do this, click the **Your Response** heading to expand the response field.
+Note that you can view your response at any time after you submit it. To do this, click the **Your Response** heading to expand the response field.
 
 .. image:: /Images/PA_S_ReviewResponse.png
    :alt: Image of the Response field collapsed and then expanded
+   :width: 550
 
 
 Assess Peer Responses
@@ -57,12 +59,13 @@ Assess Peer Responses
 
 When peer assessment starts, you'll see the original question followed by another student's response and a rubric. Above the rubric you can also see how many responses you'll assess, how many you've already assessed, and the amount of time you can expect to spend on each assessment. Below the rubric is a field where you can provide comments about the student's response.
 
+The rubric contains *criteria*, each of which has several *options*. Read the student's response and the rubric carefully, and then select the option that you think best reflects the student's response.
+
 .. image:: /Images/PA_LMS-PARubric.png
    :alt: Image of the question, response, and rubric
+   :width: 550
 
-The rubric contains *criteria*, each of which has several *options*. Read the student's response and the rubric carefully, and then select the option that you think best reflects the student's response.
-
-When you've selected options in the rubric, provide additional comments about the response. When you're done, click **Submit your assessment and move to response #<number>**.
+When you've selected options in the rubric, provide additional comments about the response in the field below the rubric. When you're done, click **Submit your assessment and move to response #<number>**.
 
 When you submit your assessment of the first student's response, another response opens for you. Assess this response in the same way that you assessed the first response, and then submit your assessment. You'll repeat these steps until you've assessed the required number of responses. The number in the upper-right corner of the rubric updates as you assess each response.
 
@@ -76,20 +79,21 @@ When you've completed enough peer assessments, your self assessment opens. You'l
 Receive Your Score and Provide Feedback
 ****************************************
 
-After you submit your self assessment, if other students are still assessing your response, you'll see the following message under **Your Grade**.
+After you submit your self assessment, if other students are still assessing your response, you'll see the following message under the **Assess Your Response** step.
 
-	Waiting for Peers to Assess Your Response
+	**Your Grade: Waiting for Peer Assessment**
 
-	Your response is still undergoing peer assessment. After your peers have assessed your response, you'll see their feedback and receive your final grade.
+	**Your response is still undergoing peer assessment. After your peers have assessed your response, you'll see their feedback and receive your final grade.**
 
 If you see this message, keep checking back periodically until peer assessment is complete.
 
 When peer assessment is complete, you can see the scores you received from all of your peers, as well as your self assessment. You can also see any additional comments that your peers have provided.
 
 .. image:: /Images/PA_AllScores.png
-   :alt: Image of a student's response with peer and self assessment scores
+   :alt: A student's response with peer and self assessment scores
+   :width: 550
 
-If you want to, you can provide feedback on the scores that you received under **Give Feedback on Peer Evaluations**.
+If you want to, you can provide feedback on the scores that you received under **Provide Feedback on Peer Assessments**.
 
 Assess Additional Peer Responses (optional)
 *******************************************