Skip to content

Commit

Permalink
Merge branch 'master' into pdesjardins/CS-1
Browse files Browse the repository at this point in the history
  • Loading branch information
Peter Desjardins committed Mar 8, 2016
2 parents d87dcee + 39f8b0f commit c10bf21
Show file tree
Hide file tree
Showing 152 changed files with 3,707 additions and 1,373 deletions.
48 changes: 33 additions & 15 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,18 @@
EdX Documentation
###################

The edx-documentation repo contains source files for most of the documentation
for edX partners and the Open edX community. This repo is managed by the edX
Documentation team.
The edx-documentation repository contains source files for most of the
documentation for edX partners and the Open edX community. This repo is managed
by the edX Documentation team.

API documentation that includes docstrings from code files is stored in the
repository of that module.
* API documentation that includes docstrings from code files is stored in the
repository of that module.

* Documentation source files for Insights is in the edx-analytics-dashboard
repository.

Documentation for developers, researchers, course staff, and students is
located in the language-specific subdirectories.
located in the language-specific subdirectories.

******************************
View Published Documentation
Expand Down Expand Up @@ -38,7 +41,7 @@ Contribute to edX Documentation

You, the user community, can help update and revise edX documentation.

EdX documentation is created using `RST`_ files and `Sphinx`_.
EdX documentation is published from `RST`_ source files using `Sphinx`_.

.. _RST: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org
Expand All @@ -52,25 +55,40 @@ Flow`_.
All pull requests need approval from edX. For more information, contact edX at
[email protected].

Before submitting a pull request, it is recommend you run the test suite on
your contribution to ensure it can be compiled without errors.
============================================
Supplying Information with a Pull Request
============================================

The edX documentation team created a `template`_ for pull request descriptions
that you are encouraged to use. You can find it on the team wiki.

.. _template: https://openedx.atlassian.net/wiki/display/DOC/Doc+Team+Pull+Request+Template

======================
Testing a Contribution
======================

To run a test compilation of a contribution, first install the prerequisites:
Before submitting a pull request, it is recommended you run the test suite on
your contribution to ensure it can be compiled into HTML format without errors.

To run a test compilation of a contribution, first install the prerequisites.

.. code::
pip install -r shared/travis_requirements.txt
Then run the tests:
Then run the tests.

.. code::
./run_tests.sh
Additionally, you can run tests for a single project:
Additionally, you can run tests for a single project. For example, to build an
HTML version of the *Installing, Configuring, and Running the Open edX
Platform* guide, you run this test.

.. code::
./run_tests.sh en_us/install_operations/
A convenience script is provided to help you develop new documentation. To use
Expand All @@ -81,7 +99,7 @@ it you must first install the optional tools, and then run the script.
pip install -r shared/tools.txt
./develop.sh en_us/install_operations/
It will output a line of text that looks like this:
It will output a line of text that looks like this.

::

Expand Down
174 changes: 118 additions & 56 deletions en_us/course_authors/source/course_features/credit_courses/proctored_exams.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,12 +75,12 @@ exam, and edX's :ref:`Online Proctoring Rules <Online Proctoring Rules>`, see
paper, calculators, or reference books.

If a particular exam in your course has a less stringent exam policy, or if
you want to allow a particular tool (for example, a calculator or pencil
and paper), contact your edX Program Manager. It is important that the
rules for your exam, if different from the "Closed Book" rules, are
communicated to the proctored exam reviewers so that learners are not
unknowingly failed for using an item that you have allowed in your exam,
but that is listed as forbidden in the proctoring rules.
you want to allow a particular tool (for example, a calculator or pencil and
paper), you can enter custom rules or rule exceptions for your exam. It is
important that the rules for your exam, if different from the "closed book"
rules, are communicated to the proctored exam reviewers so that learners'
exam attempts are not incorrectly disqualified. For more information, see
:ref:`specifying_exam_rules_and_exceptions`.


.. _Proctored Exam Session Results:
Expand Down Expand Up @@ -132,7 +132,13 @@ the due date.

.. Question for Griff or Julia
.. Do we want to give advice to course staff about planning an adequate due date? e.g. allow more time than normal for allow proctoring results to come back? Allow time for administrative tasks, especially as edX support needs to be involved in creating extra time allowances. Course staff need to allow enough time to get confirmations back from Support and also to notify students. If resolution of any technical difficulty disputes is needed, students also need adequate time to retake the exam.
.. Do we want to give advice to course staff about planning an adequate due
.. date? e.g. allow more time than normal for allow proctoring results to come
.. back? Allow time for administrative tasks, especially as edX support needs
.. to be involved in creating extra time allowances. Course staff need to allow
.. enough time to get confirmations back from Support and also to notify
.. students. If resolution of any technical difficulty disputes is needed,
.. students also need adequate time to retake the exam.
Taking a proctored exam
Expand Down Expand Up @@ -196,12 +202,12 @@ Proctoring Rules <Online Proctoring Rules>`.
paper, calculators, or reference books.

If a particular exam in your course has a less stringent exam policy, or if
you want to allow a particular tool (for example, a calculator or pencil
and paper), contact your edX Program Manager. It is important that the
rules for your exam, if different from the "Closed Book" rules, are
communicated to the proctored exam reviewers so that learners are not
unknowingly failed for using an item that you have allowed in your exam,
but that is listed as forbidden in the proctoring rules.
you want to allow a particular tool (for example, a calculator or pencil and
paper), you can enter custom rules or rule exceptions for your exam. It is
important that the rules for your exam, if different from the "closed book"
rules, are communicated to the proctored exam reviewers so that learners'
exam attempts are not incorrectly disqualified. For more information, see
:ref:`specifying_exam_rules_and_exceptions`.

Emphasize that learners must be aware of the requirements before taking the
exam, and that some of the requirements might take some preparation.
Expand Down Expand Up @@ -266,7 +272,8 @@ To enable proctored exams in your course, follow these steps.
#. Change the value of the setting to ``true``.

.. image:: ../../../../shared/images/Proctoring_AdvancedSetting.png
:alt: The "Enable Timed and Proctored Exams" advanced setting with a value of "true".
:alt: The "Enable Timed and Proctored Exams" advanced setting with a
value of "true".
:width: 500

#. Select **Save Changes** at the bottom of the page. You can now create
Expand All @@ -292,17 +299,25 @@ To create an exam that includes online proctoring, follow these steps.

#. In Studio, in your course outline, add a subsection for your exam.

#. Select the Settings icon to open the settings for the exam.
#. Select the settings icon. Set the release date, grading, and student
visibility options for the exam.

#. In the **Additional Options** section of the dialog box, select
**Proctored**.
.. This should include a reference to a general explanation of these settings.
.. The settings are not specific to proctored exams.
#. Specify the allotted time for the exam in hours and minutes.
#. Select the **Advanced** tab of the **Exam Settings** screen.

.. image:: ../../../../shared/images/Proctoring_StudioSetProctoredExam.png
:alt: The Studio subsection settings dialog showing selections for a timed
and proctored final exam.
:width: 600
#. Select **Proctored**. Specify the length of time allowed for the exam in the
**Time Allotted (HH:MM)** field. Specify the length of time in hours and
minutes.

#. If you allow learners to use tools and techniques that are prohibited by the
default rules for proctored exams, specify the custom rules and rule
exceptions for the proctored exam review team. For more information, see
:ref:`specifying_exam_rules_and_exceptions`.

For more information about the default rules for proctored exams, see
:ref:`Online Proctoring Rules <Online Proctoring Rules>`.

#. Select **Save**.

Expand Down Expand Up @@ -336,32 +351,32 @@ practice exam are required to perform the same installation step when they
prepare to take an actual proctored exam, to ensure that they are using the
latest version of the proctoring software.

.. note:: Make sure you create the practice exam as an ungraded exam.

To create a practice exam, follow these steps.

.. note:: Make sure you create the practice exam as an ungraded exam.

#. In Studio, in your course outline, add a subsection for the practice exam.

#. Give a name to the exam that clearly identifies it as a practice exam.

#. Select the Settings icon to open the settings for the exam.
#. Select the settings icon. Set the release date, grading, and student
visibility options for the exam.

#. Make sure the exam is specified as **Not Graded**.
Make sure you select **Not Graded** in the **Grade as** control.

#. In the **Additional Options** section of the dialog box, select
**Practice Proctored**.
.. This should include a reference to a general explanation of these settings.
.. The settings are not specific to proctored exams.
#. Specify the allotted time for the exam in hours and minutes.
#. Select the **Advanced** tab of the **Exam Settings** screen.

#. Select **Practice Proctored**. Specify the length of time allowed for the
exam in the **Time Allotted (HH:MM)** field. Specify the length of time in
hours and minutes.

For a practice exam, edX recommends that you specify a relatively short
duration that is appropriate for the number of example problems you
include.

.. image:: ../../../../shared/images/Proctoring_StudioSetPracticeExam.png
:alt: The Studio subsection settings dialog, showing settings for an ungraded practice proctored exam.
:width: 600

#. Select **Save**.

#. Optionally, add a text component to the exam to provide learners with
Expand All @@ -371,15 +386,55 @@ To create a practice exam, follow these steps.
The practice exam is added to the courseware, and is visible to all learners
regardless of their enrollment track.

.. _specifying_exam_rules_and_exceptions:

====================================
Specifying Exam Rules and Exceptions
====================================

You can provide custom rules and rule exceptions to the team of reviewers who
determine whether learners' exam attempts conform to the rules for proctored
exams. If your course allows learners to use tools and techniques that are
prohibited by the default rules for proctored exams, you must describe the
exceptions to the reviewers.

For more information about the default rules for proctored exams, see
:ref:`Online Proctoring Rules <Online Proctoring Rules>`.

To specify custom proctored exam rules and rule exceptions, follow these steps.

#. In Studio, open your course outline and select the subsection for the exam.

#. Select the settings icon to open the **Exam Settings** screen.

#. Select the **Advanced** tab.

#. Describe any additional rules or rule exceptions in the **Review Rules**
field.

Write clear, English-language descriptions of your exam rules. For example,
you could enter the following rules.

``Allow one blank sheet of paper and a pencil or pen. Allow a hand-held
calculator on the desk.``

#. Select **Save**.

.. note::
Your description of the additional rules and rule exceptions must be as
clear, specific, and easy to understand as possible. If the reviewers do not
understand your rules and exceptions, they may incorrectly disqualify exam
attempts. Use uncomplicated sentences and words that a global English-
speaking audience will understand.

.. _Respond to Learner Concerns about Proctored Exams:

**********************************************************
Responding to Learners' Concerns about Proctored Exams
**********************************************************

In addition to questions that can be answered in the FAQs on edx.org, or by
the :ref:`Online Proctoring Rules <Online Proctoring Rules>`, situations might
In addition to questions that can be answered in the FAQs on edx.org, or by the
:ref:`Online Proctoring Rules <Online Proctoring Rules>`, situations might
arise that require an action by edX Support.

.. contents::
Expand All @@ -399,8 +454,8 @@ your organization's Disability Services resources to decide whether and how a
learner with specific needs can be accommodated for a timed exam.

.. note:: Make sure the learner who has requested additional time does not
start taking the proctored exam before the additional time has been
approved and set up.
start taking the proctored exam before the additional time has been approved
and set up.

If it is confirmed that additional time should be allowed for a specific
student to take the exam, follow these steps.
Expand Down Expand Up @@ -497,13 +552,13 @@ Two results are possible for proctoring session reviews.
learner has not passed the proctoring review.

Some learner behavior that is listed in the Online Proctoring Rules is
discouraged but does not impact the integrity of the exam. Violations in
these cases might be flagged but learners with such flags can still receive a
**Satisfactory** result. For example, a learner is discouraged from playing music
or having a TV on in the background while they take their exam, but if their
session recording shows such behavior, it is still possible for them to
receive a **Satisfactory** result for their proctoring session results, as long as
there are no instances of suspicious activity that do seem to indicate
discouraged but does not impact the integrity of the exam. Violations in these
cases might be flagged but learners with such flags can still receive a
**Satisfactory** result. For example, a learner is discouraged from playing
music or having a TV on in the background while they take their exam, but if
their session recording shows such behavior, it is still possible for them to
receive a **Satisfactory** result for their proctoring session results, as long
as there are no instances of suspicious activity that do seem to indicate
cheating.

Activities that would cause learners to fail their proctoring session review
Expand All @@ -521,7 +576,7 @@ Viewing Proctored Session Results
=================================

At any time after learners have taken the proctored exam in your course, you
can download a .CSV file that displays the status of the proctoring session
can download a .csv file that displays the status of the proctoring session
for participating learners.

.. note:: The Proctored Session Results report only shows the result of
Expand Down Expand Up @@ -563,7 +618,8 @@ steps.
requested.

.. image:: ../../../../shared/images/Proctoring_CSVExamResultsLink.png
:alt: The link for a generated proctored exam results report in the instructor dashboard.
:alt: The link for a generated proctored exam results report in the
instructor dashboard.
:width: 600

You can open .csv files in a spreadsheet application to sort, graph, and
Expand All @@ -582,7 +638,7 @@ steps.
Understanding the Proctored Session Results File
=================================================

The .CSV file that you can download to view the status and results of
The .csv file that you can download to view the status and results of
learners' proctoring sessions contains the following fields.


Expand All @@ -592,21 +648,25 @@ learners' proctoring sessions contains the following fields.

* - Column
- Description
* - User/Email
* - user_email
- The username or email address that identifies the learner taking the
proctored exam.
* - Exam Name
* - exam_name
- The name of the proctored exam in the courseware.
* - Allowed Time
* - attempt_code
- An identifier for the exam attempt. The attempt code is an
internal identifier and is included in the report for use in
troubleshooting.
* - allowed_time_limit_mins
- The amount of time in minutes that this learner was allotted for
completing the exam.
* - Is Sample Attempt
* - is_sample_attempt
- Indicates whether this exam attempt was for a practice exam.
* - Started At
* - started_at
- The date and time that the learner started to take the proctored exam.
* - Completed At
* - completed_at
- The date and time that the learner submitted the proctored exam.
* - Status
* - status
- The status of the proctoring session review. Possible values are
``created``, ``ready to start``, ``started``, ``timed out``,
``completed``, ``submitted``, ``verified``, ``rejected``, and
Expand Down Expand Up @@ -713,7 +773,8 @@ each learner continues to run. Learners can reopen their exam in a new browser
window and continue their exam, but they will have lost time while the browser
was closed.

.. Question for Chris: how does the proctoring software view such a break in taking the exam?
.. Question for Chris: how does the proctoring software view such a break in
.. taking the exam?
Learners Close the Proctoring Software Window
Expand All @@ -740,4 +801,5 @@ to run. If learners reopen their exam in a new browser window, they can
continue their exam, but they will have lost time while the browser was
closed.

.. Question for Chris: how does the proctoring software view such a break in taking the exam?
.. Question for Chris: how does the proctoring software view such a break in
.. taking the exam?
Loading

0 comments on commit c10bf21

Please sign in to comment.