Added Example edX-Insider Course

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

docs/en_us/olx/source/demo-course/index.rst

@@ -1,11 +0,0 @@
-########################
-Tour of the DemoX OLX
-########################
-
-TBP
-
-.. toctree::
-   :maxdepth: 2
-
-
- 

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.

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

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
+  
+  <chapter display_name="Pedagogical Foundations: Constructive Learning" 
+      url_name="Week_2_Technology_enabled_constructive_learning">
+      <sequential format="Learning Sequence" graded="true" 
+          display_name="Overview (go here first)" 
+          url_name="Overview_go_here_first">
+          <vertical display_name="Week's overview" url_name="Week_s_overview">
+              <html display_name="Week overview" filename="Week_overview" 
+                  url_name="Week_overview"/>
+	          <done display_name="Read week overview" 
+	              url_name="Read_week_overview" align="right"/>
+
+
+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
+
+    <sequential display_name="In-class exercise" url_name="in_class">
+        <html display_name="Overview" url_name="overview">
+	        <p>In the on-line portion, . . . </p>
+	        <table border="0">
+	            <tr>
+	                <td align="right">3pm-3:10pm</td><td>Welcome!</td>
+	            </tr>
+	            . . .
+	        </table>
+        </html>
+        <vertical url_name="in_class_ora"></vertical>
+        <problem url_name="res_survey" filename="res_survey" 
+            display_name="Survey: What next?">
+        </problem>
+    </sequential>
+
+The student sees this sequential as:
+
+.. Image:: ../Images/Insider-first-sequential.png
+ :alt: The squential as a student views it
+
+.. include:: ../links.rst

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
+  
+  <chapter display_name="Pedagogical Foundations: Constructive Learning"  
+      url_name="Week_2_Technology_enabled_constructive_learning">
+      <sequential format="Learning Sequence" graded="true" 
+          display_name="Overview (go here first)" 
+          url_name="Overview_go_here_first">
+          <vertical display_name="Week's overview" url_name="Week_s_overview">
+              <html display_name="Week overview" filename="Week_overview" 
+                  url_name="Week_overview"/>
+
+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
+  
+  <sequential display_name="In-class exercise" url_name="in_class"> 
+      <html display_name="Overview" url_name="overview"> 
+          <p>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. 
+          </p>
+	      . . .
+      </html>
+
+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
+  
+  <vertical url_name="constructive_ora_exercise"></vertical>
+
+And:
+
+.. code-block:: html
+  
+  <vertical url_name="in_class_ora"></vertical>
+
+
+
+.. include:: ../links.rst

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<Policies>`.
  #.  :ref:`Add course assets<Course Assets>`.
  #.  :ref:`Create the course About page<The Course About Pages>`.
- #.  :ref:`Create pages in your course<Course Pages>`.
+ #.  :ref:`Create tabs, or pages, in your course<Course Tabs>`.
  #.  :ref:`Organize Courseware<Organizing Courseware>`.
  #.  :ref:`Create course components<Course Components>`.
- #.  :ref:`Create problems and tools<Problems and Tools>`.
- #.  :ref:`Create advanced components<Advanced Components>`.
+ #.  :ref:`Create problems and tools<Problems>`.

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
 
 
  

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
+.. _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

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

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
 *************************************

docs/en_us/olx/source/problem-xml/index.rst

@@ -1,4 +1,4 @@
-.. _Problems and Tools:
+.. _Problems:
 
 #################################
 Problems