diff --git a/docs/en_us/olx/source/Images/Insider-first-exercise.png b/docs/en_us/olx/source/Images/Insider-first-exercise.png new file mode 100644 index 0000000000..cb916fad52 Binary files /dev/null and b/docs/en_us/olx/source/Images/Insider-first-exercise.png differ diff --git a/docs/en_us/olx/source/Images/Insider-first-image.png b/docs/en_us/olx/source/Images/Insider-first-image.png new file mode 100644 index 0000000000..2c138f13fe Binary files /dev/null and b/docs/en_us/olx/source/Images/Insider-first-image.png differ diff --git a/docs/en_us/olx/source/Images/Insider-first-sequential.png b/docs/en_us/olx/source/Images/Insider-first-sequential.png new file mode 100644 index 0000000000..429f96c64b Binary files /dev/null and b/docs/en_us/olx/source/Images/Insider-first-sequential.png differ diff --git a/docs/en_us/olx/source/Images/edx-insider-github.png b/docs/en_us/olx/source/Images/edx-insider-github.png new file mode 100644 index 0000000000..5d8ede6dae Binary files /dev/null and b/docs/en_us/olx/source/Images/edx-insider-github.png differ diff --git a/docs/en_us/olx/source/change_log.rst b/docs/en_us/olx/source/change_log.rst index 6d01d2735e..f704fef2cb 100644 --- a/docs/en_us/olx/source/change_log.rst +++ b/docs/en_us/olx/source/change_log.rst @@ -13,16 +13,17 @@ October, 2014 * - Date - Change + * - 10/28/14 + - Added the section :ref:`Example of an OLX Course`. * - 10/23/14 - Fixed the code sample in :ref:`Script Tag Format` in the :ref:`Write Your Own Grader` chapter. * - - Fixed a bug in the :ref:`Text Input Problem XML`. * - 10/17/14 - - Provided more explanation to the introduction to :ref:`Problems and - Tools`. + - Provided more explanation to the introduction to :ref:`Problems`. * - - - Reorganized the :ref:`Problems and Tools` and :ref:`Course Components` + - Reorganized the :ref:`Problems` and :ref:`Course Components` sections to properly categorize these types of objects. * - - Updated the :ref:`ODL Directory Structure` chapter to accurately reflect @@ -33,7 +34,7 @@ October, 2014 in container objects. * - 10/07/14 - Added pages for the :ref:`Graphical Slider Tool` and - :ref:`Symbolic Response` to the :ref:`Problems and Tools` section. + :ref:`Symbolic Response` to the :ref:`Problems` section. ***************** September, 2014 diff --git a/docs/en_us/olx/source/demo-course/index.rst b/docs/en_us/olx/source/demo-course/index.rst deleted file mode 100644 index d2d1db0960..0000000000 --- a/docs/en_us/olx/source/demo-course/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -######################## -Tour of the DemoX OLX -######################## - -TBP - -.. toctree:: - :maxdepth: 2 - - - \ No newline at end of file diff --git a/docs/en_us/olx/source/directory-structure.rst b/docs/en_us/olx/source/directory-structure.rst index 06e983ad7e..29853375ef 100644 --- a/docs/en_us/olx/source/directory-structure.rst +++ b/docs/en_us/olx/source/directory-structure.rst @@ -4,13 +4,16 @@ OLX Course Structure ############################################### -See: +This chapter describes the structure of a generic OLX course. See: * `OLX and Directory File Structures`_ * `Top-level Directory`_ * `XBlock directories`_ * `edX Platform Directories`_ +See :ref:`The Structure of edX-Insider` for information on how a specific OLX course is structured. + + **************************************** OLX and Directory File Structures **************************************** @@ -49,7 +52,7 @@ content. additional directories that store the XML for XBlocks of that type. ******************* -XBlock directories +XBlock Directories ******************* edX course components can be broken out of the main ``course.xml`` file @@ -84,7 +87,7 @@ files that specify course policies and non-courseare content. The ``about`` directory contains: * ``overview.html``, which contains the content for the course overview page - students see the the Learning Management System (LMS). + that students see in the the Learning Management System (LMS). * ``short_description.html``, which contains the content for the course in the course list. @@ -98,8 +101,8 @@ See :ref:`The Course About Pages` for more information. The ``info`` directory contains: -* ``handouts.html``, which contains the contain for the Course Handouts page in - the course. +* ``handouts.html``, which contains the content for the **Course Handouts** + page in the course. * ``updates.html``, which contains the course updates students see when opening a course. diff --git a/docs/en_us/olx/source/example-course/index.rst b/docs/en_us/olx/source/example-course/index.rst new file mode 100644 index 0000000000..ae58b74fdb --- /dev/null +++ b/docs/en_us/olx/source/example-course/index.rst @@ -0,0 +1,26 @@ +.. _Example of an OLX Course: + +######################## +Example of an OLX Course +######################## + +OLX is a flexible system that you can use to create edX courses in many ways. +While there is no best way to structure courses in all situations, there are +best practices that help make an OLX course easier to create and maintain. + +In this section, we use a course, `edX-Insider`_, as an example of how to +create an OLX course. We examine the overall structure of edX-Insider, as well +as how the courseware is defined. + +The files for `edX-Insider`_ are stored in GitHub, so you can explore how the +course is made for yourself. + +See the following chapters for more information. + +.. toctree:: + :maxdepth: 2 + + insider-structure + insider-course-xml + +.. include:: ../links.rst \ No newline at end of file diff --git a/docs/en_us/olx/source/example-course/insider-course-xml.rst b/docs/en_us/olx/source/example-course/insider-course-xml.rst new file mode 100644 index 0000000000..0b69a986d6 --- /dev/null +++ b/docs/en_us/olx/source/example-course/insider-course-xml.rst @@ -0,0 +1,86 @@ +.. _The edX-Insider course.xml File: + +################################### +The edX-Insider ``course.xml`` File +################################### + +The courseware for `edX-Insider`_ is defined in the `course.xml`_ file and +follows the organization described in :ref:`The Courseware Structure`. + +See: + +* `edX-Insider Course Hierarchy`_ +* `Sequentials that Contain XBlocks`_ + + +***************************** +edX-Insider Course Hierarchy +***************************** + +The edX-Insider courseware is organized into chapters, sequentials, and +verticals. + +For example, the following XML defines the first chapter, sequential, and +vertical in the course: + +.. code-block:: xml + + + + + + + + +The vertical ``Week's Overview`` contains an HTML component that references the +file ``Week_overview`` in the ``HTML`` directory. + +Students see this content in the Learning Management System as: + +.. Image:: ../Images/Insider-first-image.png + :alt: The HTML component as a student views it + + +********************************* +Sequentials that Contain XBlocks +********************************* + +One advantage of OLX is the flexibility it allows in how you organize your +course. For example, edX-Insider demonstrates that you can nest XBlocks and +problems directly in a sequential, without the need for a vertical. This +streamlines the course creation process while maintaining consistency in how +students interact with courseware. + +The following XML defines a sequential that has as children an HTML XBlock, a +reference to a vertical that is defined in another file, and a reference to a +problem defined in another file: + +.. code-block:: xml + + + +

In the on-line portion, . . .

+ + + + + . . . +
3pm-3:10pmWelcome!
+ + + + + + +The student sees this sequential as: + +.. Image:: ../Images/Insider-first-sequential.png + :alt: The squential as a student views it + +.. include:: ../links.rst \ No newline at end of file diff --git a/docs/en_us/olx/source/example-course/insider-structure.rst b/docs/en_us/olx/source/example-course/insider-structure.rst new file mode 100644 index 0000000000..5cca9c4cc7 --- /dev/null +++ b/docs/en_us/olx/source/example-course/insider-structure.rst @@ -0,0 +1,219 @@ +.. _The Structure of edX-Insider: + +############################# +The Structure of edX-Insider +############################# + +This chapter describes the structure of the `edX-Insider`_ course. See: + +* `edX-Insider and Directory File Structures`_ +* `Top-level Directory`_ +* `The HTML XBlock Directory`_ +* `Platform Directories`_ + +For information on how a generic OLX course is structured, see :ref:`ODL +Directory Structure`. + +.. note:: + The structure and content of edX-Insider may change before this documentation + is updated. + +****************************************** +edX-Insider and Directory File Structures +****************************************** + +All files and sub-directores that comprise edX-Insider are stored in the +`Ongoing`_ directory in the edX-Insider Git repository. + +.. Image:: ../Images/edx-insider-github.png + :alt: The edX-Insider course in GitHub + + + +******************** +Top-level Directory +******************** + +The `Ongoing`_ directory in the edX-Insider Git repository contains the +``course.xml`` file as well as XBlock and Platform directories. + +The `course.xml`_ file contains the XML for the courseware. All chapters and +sequentials are defined in ``course.xml``. + +Most verticals are defined in ``course.xml``; two verticals are referenced +in other files. + +The content of some HTML XBlocks is embedded within ``course.xml``; other HTML +XBlocks are referenced in other files. + +Problems are referenced in other files. + +See :ref:`The edX-Insider course.xml File` for more information. + + +****************************** +The HTML XBlock Directory +****************************** + +While some HTML content is embedded in ``course.xml``, many HTML XBlocks are +stored as separate files in the ``HTML`` directory. + +============================== +Example of a Referenced XBlock +============================== + +You can reference an XBlock from the ``course.xml`` file. + +For example, in ``course.xml``, the first vertical in the courseware contains a +single HTML XBlock with the display name ``Week overview``, which references +``Week_overview`` in the ``url_name`` attribute: + +.. code-block:: html + + + + + + +There is a file called ``Week_overview.html`` in the ``html`` directory that +contains the content for that HTML component. For detailed information, see the +`Week_overview.html`_ file in GitHub. + +For a student, that HTML component appears as the first unit of the course: + +.. Image:: ../Images/Insider-first-image.png + :alt: The HTML component as a student views it + + +============================== +Example of an Inline XBlock +============================== + +You can include an XBlock content within the ``course.xml`` file. You may do +this for ease of reading and maintenance when you do not need to reuse the +content. + +For example, in ``course.xml``, the sequential with the display name ``In-class +exercise`` contains embedded HTML content: + +.. code-block:: html + + + +

In the on-line portion, + we examined a way we used technology to allow efficient + implementation of one theory from learning science – constructive + learning – in edX. In designing the edX platform, we applied many + such techniques. We took aspects of mastery learning, project- + based learning, gamification and others. Other platforms have + sophisticated techniques for targeting specific student + misconceptions, enabling a range of student social experiences, + assessing teacher performance, and hundreds of other research- + based techniques. We would like to give you a chance to practice + with designing software to enable good pedagogy. +

+ . . . + + +For a student, that HTML component appears as unit of the course in the same +way as a referenced HTML component does: + +.. Image:: ../Images/Insider-first-exercise.png + :alt: The HTML component as a student views it + + +******************** +Platform Directories +******************** + +The edX-Insider course contains information in the course sub-directories as +described below. + +==================== +``about`` Directory +==================== + +The ``about`` directory contains: + +* ``overview.html``, which contains the content for the course overview page that students see in the the Learning Management System (LMS). + +* ``short_description.html``, which contains the content for the course in the + course list. + +See :ref:`The Course About Pages` for more information. + + +==================== +``info`` Directory +==================== + +The ``info`` directory contains: + +* ``handouts.html``, which contains the content for the **Course Handouts** + page in the course. + +* ``updates.html``, which contains the course updates students see when opening + a course. + +======================= +``policies`` Directory +======================= + +The ``policies`` directory contains: + +* ``assets.json``, which defines all files used in the course, such as images. + +* A course directory named ``Ongoing``, which contains: + + * ``grading_policy.json``, which defines how student work is graded in the + course. + + * ``policy.json``, which defines various settings in the course. + +See :ref:`Course Policies` for more information. + +==================== +``static`` Directory +==================== + +The ``static`` directory contains the files used in the course, such as images +or PDFs. + +See :ref:`Course Assets` for more information. + +======================= +``vertical`` Directory +======================= + +The ``vertical`` directory contains the XML for two verticals used in the +course: + +* ``constructive_ora_exercise.xml`` +* ``in_class_ora.xml`` + +You can embed verticals in the ``course.xml`` file, and this is usually the +most straightforward option. However, with OLX, you can also store XML for +verticals in separate files in the ``vertical`` directory. + +In this case, verticals for open response assessments are stored in their own +files. See `Creating a Peer Assessment`_ for more information. + +The vertical files are referenced in ``course.xml`` as follows: + +.. code-block:: html + + + +And: + +.. code-block:: html + + + + + +.. include:: ../links.rst \ No newline at end of file diff --git a/docs/en_us/olx/source/getting-started.rst b/docs/en_us/olx/source/getting-started.rst index 363e68d50e..f1980cb055 100644 --- a/docs/en_us/olx/source/getting-started.rst +++ b/docs/en_us/olx/source/getting-started.rst @@ -9,8 +9,7 @@ To develop your course in OLX, you complete the following steps: #. :ref:`Define course policies`. #. :ref:`Add course assets`. #. :ref:`Create the course About page`. - #. :ref:`Create pages in your course`. + #. :ref:`Create tabs, or pages, in your course`. #. :ref:`Organize Courseware`. #. :ref:`Create course components`. - #. :ref:`Create problems and tools`. - #. :ref:`Create advanced components`. \ No newline at end of file + #. :ref:`Create problems and tools`. \ No newline at end of file diff --git a/docs/en_us/olx/source/index.rst b/docs/en_us/olx/source/index.rst index 51a5d26a4d..044358d6a9 100644 --- a/docs/en_us/olx/source/index.rst +++ b/docs/en_us/olx/source/index.rst @@ -26,9 +26,8 @@ This document is intended for those developing edX courses through Open Learning organizing-course/index components/index problem-xml/index - tools/index + example-course/index drafts/index - demo-course/index diff --git a/docs/en_us/olx/source/links.rst b/docs/en_us/olx/source/links.rst index 47bbb3b423..0224456464 100644 --- a/docs/en_us/olx/source/links.rst +++ b/docs/en_us/olx/source/links.rst @@ -5,4 +5,14 @@ .. _manual-testing-complete: https://github.com/edx/edx-platform/tree/master/common/test/data/manual-testing-complete -.. _LONCAPA XML format: https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro \ No newline at end of file +.. _LONCAPA XML format: https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro + +.. _edX-Insider: https://github.com/pmitros/edX-Insider + +.. _Ongoing: https://github.com/pmitros/edX-Insider/tree/master/Ongoing + +.. _Week_overview.html: https://github.com/pmitros/edX-Insider/blob/master/Ongoing/html/Week_overview.html + +.. _Creating a Peer Assessment: http://edx.readthedocs.org/projects/edx-open-response-assessments/en/latest/index.html + +.. _course.xml: https://github.com/pmitros/edX-Insider/blob/master/Ongoing/course.xml \ No newline at end of file diff --git a/docs/en_us/olx/source/organizing-course/course-structure-overview.rst b/docs/en_us/olx/source/organizing-course/course-structure-overview.rst index 692e58e4ce..26cdffa67b 100644 --- a/docs/en_us/olx/source/organizing-course/course-structure-overview.rst +++ b/docs/en_us/olx/source/organizing-course/course-structure-overview.rst @@ -1,9 +1,11 @@ +.. _OLX Course Building Blocks: + ############################### OLX Course Building Blocks ############################### -Before you begin building OLX, you should understand the -building blocks of an edX course. See: +Before you begin building OLX, you should understand the building blocks of an +edX course. See: * `Courseware`_ * `Supplemental Course Content`_ @@ -20,7 +22,7 @@ OLX: * Course chapters are at the top level of your course and typically represent a time period. In Studio, chapters are called *sections*. -* A section contains one or more children which correspond to +* A chapter contains one or more children which correspond to top-level pages in the course. In Studio, these are called 'subsections' and are currently restricted to ``sequential`` elements at this level. OLX supports any XBlock at this level. @@ -32,8 +34,7 @@ OLX: and children of ``vertical`` elements are leaf elements (called modules). * :ref:`Course Components` - * :ref:`Problems and Tools` - * :ref:`Advanced Components` + * :ref:`Problems` For more information, see :ref:`The Courseware Structure`. @@ -54,7 +55,7 @@ following list describes the types of supported content: more information, see :ref:`Course Assets`. * Course pages are custom pages that you can have appear in the top navigation - menu of your course. For more information, see :ref:`Course Pages`. + menu of your course. For more information, see :ref:`Course Tabs`. **************************** Course Policies diff --git a/docs/en_us/olx/source/organizing-course/course-xml-file.rst b/docs/en_us/olx/source/organizing-course/course-xml-file.rst index 8bfc27e937..9949e80c92 100644 --- a/docs/en_us/olx/source/organizing-course/course-xml-file.rst +++ b/docs/en_us/olx/source/organizing-course/course-xml-file.rst @@ -14,6 +14,8 @@ See: * `Course Sequentials`_ * `Course Verticals`_ +For an example of an ``course.xml`` file, see :ref:`The edX-Insider course.xml File`. + ************************************* The ``course.xml`` File ************************************* diff --git a/docs/en_us/olx/source/problem-xml/index.rst b/docs/en_us/olx/source/problem-xml/index.rst index e63b7e331f..7375adf599 100644 --- a/docs/en_us/olx/source/problem-xml/index.rst +++ b/docs/en_us/olx/source/problem-xml/index.rst @@ -1,4 +1,4 @@ -.. _Problems and Tools: +.. _Problems: ################################# Problems