diff --git a/lms/djangoapps/courseware/docs/decisions/0004-personalized-relative-dates.rst b/lms/djangoapps/courseware/docs/decisions/0004-personalized-relative-dates.rst new file mode 100644 index 0000000000000000000000000000000000000000..fe6503b45c6087642be58b65fd21e584c9b89c07 --- /dev/null +++ b/lms/djangoapps/courseware/docs/decisions/0004-personalized-relative-dates.rst @@ -0,0 +1,135 @@ +0004. Personalized/Relative Dates in Courseware +*********************************************** + +~~~~~~~ +Context +~~~~~~~ + +Self-paced courses are, based on the experience of users on edx.org, +less engaging and less likely to be completed, than instructor-paced courses. +Research shows that learners are better able to complete a course of study +when that course gives them multiple incremental deadlines along the way, +rather than one single deadline at the end of the course. Unfortunately, +self-paced courses are currently only able to offer the latter experience. + +``edx-when`` is a library currently used by ``edx-platform`` to provide a +read-optimized view of the dates associated with course content. It is updated +when a course is published, and stores dates in a dedicated table in the +relational database. + +~~~~~~~~~~~ +Definitions +~~~~~~~~~~~ + +Absolute date: + A date and time, represented in python as `datetime.datetime`. +Relative date: + A date and time offset, represented in python as `datetime.timedelta`. + To convert to an Absolute date, the offset is added to a students Content + Availability Date. +Content Availability Date: + The students enrollment date, or the course start date, whichever is later. + +~~~~~~~~ +Decision +~~~~~~~~ + +In order to support incremental deadlines in self-paced courses, we want +to extend edx-platform with the following capabilities: + +1. Extend the api provided by ``edx-when`` used in the LMS to so that + the LMS can ask for dates for students (supplying their ``Schedule``), and + ``edx-when`` will return an absolute date (even if the date defined by + Studio is relative). +2. When a self-paced course is published, add relative due dates to it, + evenly spaced across the expected duration of the course, unless the + course already has relative dates attached to content. + + a. These dates should be pushed into ``edx-when`` + by Studio. We will move the existing ``edx-when`` course-publish signal + handler out into Studio, and have it use exposed ``edx-when`` APIs to + write in absolute or relative dates. + b. While there are no current plans to allow Studio authors to author + relative dates, by making the evenly-spacing only occur if there + is no existing relative dates on the course, we leave ourselves the + ability to add future studio authoring without changing ``edx-when``. + c. Adding the relative dates on course-publish, and storing them in ``edx-when``, + rather than inferring them at run-time while reading from ``edx-when`` + means that we have the course structure in-hand (from the course + publish), and that ``edx-when`` will remain a full listing of all dates + in the course. If, instead, the LMS inferred relative dates when they + weren't set in ``edx-when``, then new date-based functionality in the + future would need to either read through a specific api that would + inject the programmatic dates, or would have to infer its own dates. +3. No new fields would be added to XBlocks at this time to represent relative + dates. There is no studio authoring component for this feature, and the LMS + Xblock runtime would contextualize relative dates for a specific student + when supplying them to XBlock fields. +4. Update the documentation in ``edx-when`` to capture our current + understanding of its responsibilities. To wit, ``edx-when`` exists to give + the LMS a single place to ask "What does this student have coming up, + across one or many courses?", and get a fast, efficient answer. To that + end, the ``schedules`` django app should be moved into ``edx-when``, and + it will handle any future features related to the ability to scale pacing + in self-paced courses faster or slower. ``edx-when`` is thus both a + performance optimization(because it is optimized for reading), and the + single dedicated owner of a particular user's schedule of course content. + + However, it does not include information about course-level administrative + dates, such as the upgrade deadline, so that will need to be disentangled + from the Schedule model (or we'll need to expand ``edx-when`` with + additional notions of date semantics). +5. ``edx-when``, and the ``schedules`` app, should keep history, so that we + can determine at analysis time what their schedule was when they answered + a problem. Using a simple history table should be sufficient to also + support showing a user the history of changes to their own schedule. + +~~~~~~ +Status +~~~~~~ + +Proposed + +~~~~~~~~~~~~ +Consequences +~~~~~~~~~~~~ + +Once implemented, self-paced courses in the LMS would begin to have +due dates for course content that are consistent between users, but that +are personalized based on when a user started a course. We would be open +to exploring future functionality for allowing users to adjust their schedule +by resetting their effective course start time, or speeding up or slowing +down their pacing. + +~~~~~~~~~~~~~~~~~~~~~ +Rejected Alternatives +~~~~~~~~~~~~~~~~~~~~~ + +Expand Capabilities of XBlock DateField +--------------------------------------- + +It's tempting to allow the XBlock DateField to support relative dates as well +as absolute dates. However, that would cause OLX backwards incompatibility +when the relative dates were exported into the same field as the existing +absolute dates. + +Offset From Previous Content +---------------------------- + +Rather than considering date offsets to be relative to the start of the users +schedule, maybe they should be relative to the previous item of content. +That way, when you reset a schedule (or change a users pacing), you can just +modify future content. + +The difficulties with this proposal are: + +1. In order to find the actual absolute date of a piece of content, you need + to access all of the content before that item in the course, and then + sum up all of their offsets. This makes it harder to easily query all + upcoming due-dates over multiple courses. +2. When a user resets their schedule, they probably want to adjust previous + dates as well, so that they can go back and answer problems that they + missed. If that's the case, then adjusting the start date based on the + newly requested extension will make it easier update old and new content + consistently. +