Update documentation.

README.md

-Problem Builder XBlock
-----------------------
+Problem Builder and Step Builder
+--------------------------------
 
 [![Build Status](https://travis-ci.org/open-craft/problem-builder.svg?branch=master)](https://travis-ci.org/open-craft/problem-builder)
 
-This XBlock allows creation of questions of various types and simulating the
-workflow of real-life mentoring, within an edX course.
+This repository provides two XBlocks: Problem Builder and Step Builder.
 
-It supports:
+Both blocks allow to create questions of various types. They can be
+used to simulate the workflow of real-life mentoring, within an edX
+course.
+
+Supported features include:
 
 * **Free-form answers** (textarea) which can be shared accross
   different XBlock instances (for example, to allow a student to
-  review and edit an answer he gave before).
-* **Self-assessment MCQs** (multiple choice), to display predetermined
-  feedback to a student based on his choices in the
+  review and edit an answer they gave before).
+* **Self-assessment MCQs** (multiple choice questions), to display
+  predetermined feedback to a student based on his choices in the
   self-assessment. Supports rating scales and arbitrary answers.
 * **MRQs (Multiple Response Questions)**, a type of multiple choice
-  question that allows the student to choose more than one choice.
+  question that allows the student to select more than one choice.
 * **Answer recaps** that display a read-only summary of a user's
   answer to a free-form question asked earlier in the course.
 * **Progression tracking**, to require that the student has
@@ -26,15 +29,15 @@ It supports:
 * **Dashboards**, for displaying a summary of the student's answers
   to multiple choice questions. [Details](doc/Dashboard.md)
 
-The screenshot shows an example of a problem builder block containing a
-free-form question, two MCQs and one MRQ.
+The following screenshot shows an example of a Problem Builder block
+containing a free-form question, two MCQs and one MRQ:
 
 ![Problem Builder Example](doc/img/mentoring-example.png)
 
 Installation
 ------------
 
-Install the requirements into the python virtual environment of your
+Install the requirements into the Python virtual environment of your
 `edx-platform` installation by running the following command from the
 root folder:
 
@@ -45,14 +48,20 @@ $ pip install -r requirements.txt
 Enabling in Studio
 ------------------
 
-You can enable the Problem Builder XBlock in studio through the advanced
-settings.
+You can enable the Problem Builder and Step Builder XBlocks in Studio
+by modifying the advanced settings for your course:
+
+1. From the main page of a specific course, navigate to **Settings** ->
+   **Advanced Settings** from the top menu.
+2. Find the **Advanced Module List** setting.
+3. To enable Problem Builder for your course, add `"problem-builder"`
+   to the modules listed there.
+4. To enable Step Builder for your course, add `"step-builder"` to the
+   modules listed there.
+5. Click the **Save changes** button.
 
-1. From the main page of a specific course, navigate to `Settings ->
-   Advanced Settings` from the top menu.
-2. Check for the `advanced_modules` policy key, and add `"problem-builder"`
-   to the policy value list.
-3. Click the "Save changes" button.
+Note that it is perfectly fine to enable both Problem Builder and Step
+Builder for your course -- the blocks do not interfere with each other.
 
 Usage
 -----

doc/Usage.md

-Mentoring Block Usage
+Problem Builder Usage
 =====================
 
-When you add the `Problem Builder` component to a course in the studio, the
-built-in editing tools guide you through the process of configuring the
-block and adding individual questions.
+When you add the **Problem Builder** component to a course in the
+studio, the built-in editing tools guide you through the process of
+configuring the block and adding individual questions.
 
 ### Problem Builder modes
 
 There are 2 mentoring modes available:
 
-* *standard*: Traditional mentoring. All questions are displayed on the
+* **standard**: Traditional mentoring. All questions are displayed on the
   page and submitted at the same time. The students get some tips and
   feedback about their answers. This is the default mode.
 
-* *assessment*: Questions are displayed and submitted one by one. The
+* **assessment**: Questions are displayed and submitted one by one. The
   students don't get tips or feedback, but only know if their answer was
   correct. Assessment mode comes with a default `max_attempts` of `2`.
 
-Below are some LMS screenshots of a problem builder block in assessment mode.
+**Note that assessment mode is deprecated**: In the future, Problem
+Builder will only provide functionality that is currently part of
+standard mode. Assessment mode will remain functional for a while to
+ensure backward compatibility with courses that are currently using
+it. If you want to use assessment functionality for a new course,
+please use the Step Builder XBlock (described below).
+
+Below are some LMS screenshots of a Problem Builder block in assessment mode.
 
 Question before submitting an answer:
 
@@ -35,9 +42,71 @@ Score review and the "Try Again" button:
 
 ![Assessment Step 4](img/assessment-4.png)
 
-### Free-form Question
 
-Free-form questions are represented by a "Long Answer" component. 
+Step Builder Usage
+==================
+
+The Step Builder XBlock replaces assessment mode functionality of the
+Problem Builder XBlock, while allowing to group questions into explict
+steps:
+
+Instead of adding questions to Step Builder itself, you'll need to add
+one or more **Mentoring Step** blocks to Step Builder. You can then
+add one or more questions to each step. This allows you to group
+questions into logical units (without being limited to showing only a
+single question per step). As students progress through the block,
+Step Builder will display one step at a time. All questions belonging
+to a step need to be completed before the step can be submitted.
+
+In addition to regular steps, Step Builder also provides a **Review
+Step** block which allows students to review their performance, and to
+jump back to individual steps to review their answers (if **Extended
+feedback** setting is on and maximum number of attempts has been
+reached). Note that only one such block is allowed per instance.
+
+**Screenshots: Step**
+
+Step with multiple questions (before submitting it):
+
+![Step with multiple questions, before submit](img/step-with-multiple-questions-before-submit.png)
+
+Step with multiple questions (after submitting it):
+
+![Step with multiple questions, after submit](img/step-with-multiple-questions-after-submit.png)
+
+As indicated by the orange check mark, this step is *partially*
+correct (i.e., some answers are correct and some are incorrect or
+partially correct).
+
+**Screenshots: Review Step**
+
+Unlimited attempts available:
+
+![Unlimited attempts available](img/review-step-unlimited-attempts-available.png)
+Limited attempts, some attempts remaining:
+
+![Some attempts remaining](img/review-step-some-attempts-remaining.png)
+
+Limited attempts, no attempts remaining, extended feedback off:
+
+![No attempts remaining, extended feedback off](img/review-step-no-attempts-remaining-extended-feedback-off.png)
+
+Limited attempts, no attempts remaining, extended feedback on:
+
+![No attempts remaining, extended feedback on](img/review-step-no-attempts-remaining-extended-feedback-on.png)
+
+**Screenshots: Step-level feedback**
+
+Reviewing performance for a single step:
+
+![Reviewing performance for single step](img/reviewing-performance-for-single-step.png)
+
+Question Types
+==============
+
+### Free-form Questions
+
+Free-form questions are represented by a **Long Answer** component.
 
 Example screenshot before answering the question:
 
@@ -47,39 +116,41 @@ Screenshot after answering the question:
 
 ![Answer Complete](img/answer-2.png)
 
-You can add "Long Answer Recap" components to problem builder blocks later on
-in the course to provide a read-only view of any answer that the student
-entered earlier.
+You can add **Long Answer Recap** components to problem builder blocks
+later on in the course to provide a read-only view of any answer that
+the student entered earlier.
 
 The read-only answer is rendered as a quote in the LMS:
 
 ![Answer Read-Only](img/answer-3.png)
 
-### Multiple Choice Questions (MCQ)
+### Multiple Choice Questions (MCQs)
 
 Multiple Choice Questions can be added to a problem builder component and
 have the following configurable options:
 
-* Question - The question to ask the student
-* Message - A feedback message to display to the student after they
+* **Question** - The question to ask the student
+* **Message** - A feedback message to display to the student after they
   have made their choice.
-* Weight - The weight is used when computing total grade/score of
+* **Weight** - The weight is used when computing total grade/score of
   the problem builder block. The larger the weight, the more influence this
   question will have on the grade. Value of zero means this question
   has no influence on the grade (float, defaults to `1`).
-* Correct Choice - Specify which choice[s] is considered correct. If
+* **Correct Choice[s]** - Specify which choice[s] are considered correct. If
   a student selects a choice that is not indicated as correct here,
   the student will get the question wrong.
 
-Using the Studio editor, you can add "Custom Choice" blocks to the MCQ.
-Each Custom Choice represents one of the options from which students
-will choose their answer.
+Using the Studio editor, you can add **Custom Choice** blocks to an
+MCQ. Each Custom Choice represents one of the options from which
+students will choose their answer.
 
-You can also add "Tip" entries. Each "Tip" must be configured to link
-it to one or more of the choices. If the student chooses a choice, the
+You can also add **Tip** entries. Each Tip must be configured to link
+it to one or more of the choices. If the student selects a choice, the
+tip will be displayed.
 
+**Screenshots**
 
-Screenshot: Before attempting to answer the questions:
+Before attempting to answer the questions:
 
 ![MCQ Initial](img/mcq-1.png)
 
@@ -91,7 +162,7 @@ After successfully completing the questions:
 
 ![MCQ Success](img/mcq-3.png)
 
-#### Rating MCQ
+#### Rating Questions
 
 When constructing questions where the student rates some topic on the
 scale from `1` to `5` (e.g. a Likert Scale), you can use the Rating
@@ -100,11 +171,10 @@ The `Low` and `High` settings specify the text shown next to the
 lowest and highest valued choice.
 
 Rating questions are a specialized type of MCQ, and the same
-instructions apply. You can also still add "Custom Choice" components
+instructions apply. You can also still add **Custom Choice** components
 if you want additional choices to be available such as "I don't know".
 
-
-### Self-assessment Multiple Response Questions (MRQ)
+### Self-assessment Multiple Response Questions (MRQs)
 
 Multiple Response Questions are set up similarly to MCQs. The answers
 are rendered as checkboxes. Unlike MCQs where only a single answer can
@@ -113,24 +183,26 @@ time.
 
 MRQ questions have these configurable settings:
 
-* Question - The question to ask the student
-* Required Choices - For any choices selected here, if the student
+* **Question** - The question to ask the student
+* **Required Choices** - For any choices selected here, if the student
   does *not* select that choice, they will lose marks.
-* Ignored Choices - For any choices selected here, the student will
+* **Ignored Choices** - For any choices selected here, the student will
   always be considered correct whether they choose this choice or not.
 * Message - A feedback message to display to the student after they
   have made their choice.
-* Weight - The weight is used when computing total grade/score of
+* **Weight** - The weight is used when computing total grade/score of
   the problem builder block. The larger the weight, the more influence this
   question will have on the grade. Value of zero means this question
   has no influence on the grade (float, defaults to `1`).
-* Hide Result - If set to True, the feedback icons next to each
-  choice will not be displayed (This is false by default).
+* **Hide Result** - If set to `True`, the feedback icons next to each
+  choice will not be displayed (This is `False` by default).
 
-The "Custom Choice" and "Tip" components work the same way as they
+The **Custom Choice** and **Tip** components work the same way as they
 do when used with MCQs (see above).
 
-Screenshot - Before attempting to answer the questions:
+**Screenshots**
+
+Before attempting to answer the questions:
 
 ![MRQ Initial](img/mrq-1.png)
 
@@ -146,24 +218,33 @@ After successfully completing the questions:
 
 ![MRQ Success](img/mrq-4.png)
 
+Other Components
+================
+
 ### Tables
 
-The problem builder table allows you to present answers to multiple
-free-form questions in a concise way. Once you create an "Answer
-Recap Table" inside a Mentoring component in Studio, you will be
-able to add columns to the table. Each column has an optional
-"Header" setting that you can use to add a header to that column.
-Each column can contain one or more "Answer Recap" element, as
-well as HTML components.
+Tables allow you to present answers to multiple free-form questions in
+a concise way. Once you create an **Answer Recap Table** inside a
+Mentoring component in Studio, you will be able to add columns to the
+table. Each column has an optional **Header** setting that you can use
+to add a header to that column. Each column can contain one or more
+**Answer Recap** elements, as well as HTML components.
 
 Screenshot:
 
 ![Table Screenshot](img/mentoring-table.png)
 
+### "Dashboard" Self-Assessment Summary Block
+
+[Instructions for using the "Dashboard" Self-Assessment Summary Block](Dashboard.md)
+
+Configuration Options
+====================
+
 ### Maximum Attempts
 
-You can set the number of maximum attempts for the unit completion by
-setting the Max. Attempts option of the Mentoring component.
+You can limit the number of times students are allowed to complete a
+Mentoring component by setting the **Max. attempts allowed** option.
 
 Before submitting an answer for the first time:
 
@@ -173,12 +254,8 @@ After submitting a wrong answer two times:
 
 ![Max Attempts Reached](img/max-attempts-reached.png)
 
-### Custom tip popup window size
+### Custom Window Size for Tip Popups
 
-You can specify With and Height attributes of any Tip component to
-customize the popup window size. The value of those attribute should
-be valid CSS (e.g. `50px`).
-
-### "Dashboard" Self-Assessment Summary Block
-
-[Instructions for using the "Dashboard" Self-Assessment Summary Block](Dashboard.md)
+You can specify **Width** and **Height** attributes of any Tip
+component to customize the popup window size. The value of those
+attributes should be valid CSS (e.g. `50px`).