Open Learning XML Guide

Owned by Alison Hodges
Last updated: Apr 03, 2023 by Feanil Patel

Background

When edX launched its first few courses, there was no Studio with a user interface for setting up courses. Instead, courses were developed using edX's "open learning XML" or OLX. When Studio was released, not every capability that was available through OLX was duplicated into the UI. Many of the courses that MIT launched early on are still being re-run today, and they can and do contain unique or rarely used features that are only available by editing the underlying OLX.

After promoting the use of Studio pretty much exclusively to newer partner course teams, in mid FY2015 OLX was again thought to have value for a wider community. An MVP of the OLX guide was written very quickly late in FY2015, to expand adoption. However, interest then waned, and the MVP was never finished. Numerous gaps remain, and there has been no emphasis on keeping what was published up to date.

The "OLX guide" is something of a misnomer, as JSON files are also described.

Audiences

Technically-minded course teams are the main audience.

  • The Advanced Editor in Studio, which course teams use to edit the core basic and advanced CAPA problems, exposes OLX to all course teams. As a result, there is some overlap between the OLX guide and the Building and Running an (Open) edX Course guide.
  • Course exports from Studio result in a set of files in OLX.
  • The weekly data packages produced for partners contain an export of every course.  As a result, there is some overlap between the OLX guide and the Research guide.

Tools

The RST source files that define the structure of the OLX guide are in the GitHub edx-documentation repo, in the { language }/OLX/source directory.  You can use Sublime or another text editor to edit the RST files, and render and publish HTML and PDF with ReadTheDocs (the project is "edX Open Learning XML"). See Documentation Tools.

In an effort to reduce duplication, the files that describe the use of OLX in the advanced editor for core CAPA problems, are also used in the two versions of the Buiding and Running an (Open) edX Course guide. The files in the { language }/OLX/source/problem-xml directory that describe CAPA problems take advantage of the RST include directive.

For example, if you open the checkbox.rst file, you see a single line directing you to another file:

.. include:: ../../../shared/exercises_tools/checkbox.rst


This directive inserts all of the information that is found in the "include" file into the OLX guide. If you navigate to the "shared" checkbox.rst file, that is where you see a complete description of concepts and procedures for not only using the advanced editor to edit OLX in Studio, but other features in Studio as well.  The same "shared" checkbox.rst file was initially written for, and is "include"d into, the course_authors/source/exercises_tools/checkbox.rst file and the open_edx_course_authors/source/exercises_tools/checkbox.rst file.

Use of the include directive is an important tool for reducing errors and translation costs, but it does mean that a single file can be serving multiple audiences, and should therefore be approached and edited with healthy respect for possible consequences.

(Course structure information was added to the Researcher's guide after it was written for the OLX guide, and file sharing with the include directive is not used for information that overlaps between the guides.)

Checklist

  • Does the change have an effect on the course structure? If so, it is likely to have some effect on the OLX guide.
  • If the change has an effect on the course structure, it might mean that updates are needed to both the OLX guide and the Research guide.
  • Does the new or changed feature add or modify OLX elements or attributes or course JSON files?  (Example: A new feature allows you to make course pages visible to a specific group of course participants only. How will course teams and researchers see that in the files created by a course export?)
  • Does the change have an effect on CAPA problems? If so, leave information in the shared files about using Studio untouched, other than to identify changes in the OLX.
  • Because MIT courses use OLX heavily, an FYI tag in your PR to the MIT PM Mike Martin (Deactivated) and to members of the ODL would be a very helpful gesture.