From cd9476b5451c35d97aedac0d8f56c45b7929fc32 Mon Sep 17 00:00:00 2001
From: Piotr Mitros <pmitros@mitx.mit.edu>
Date: Wed, 8 Oct 2014 14:25:56 -0400
Subject: [PATCH] First pass at improving OLX docs

---
 .../olx/source/advanced-components/index.rst  |  15 ---
 .../components/discussion-components.rst      |  21 +++-
 .../olx/source/components/html-components.rst |  24 +++-
 docs/en_us/olx/source/components/index.rst    |  15 ++-
 .../source/components/video-components.rst    |  18 ++-
 docs/en_us/olx/source/directory-structure.rst | 118 +++++++++---------
 docs/en_us/olx/source/index.rst               |   3 +-
 .../course-structure-overview.rst             |  24 ++--
 .../organizing-course/course-xml-file.rst     |   9 +-
 docs/en_us/olx/source/pages/pages.rst         |   7 +-
 docs/en_us/olx/source/problem-xml/index.rst   |  26 ++--
 11 files changed, 154 insertions(+), 126 deletions(-)
 delete mode 100644 docs/en_us/olx/source/advanced-components/index.rst

diff --git a/docs/en_us/olx/source/advanced-components/index.rst b/docs/en_us/olx/source/advanced-components/index.rst
deleted file mode 100644
index 5bc47d9717..0000000000
--- a/docs/en_us/olx/source/advanced-components/index.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-.. _Advanced Components:
-
-#################################
-Advanced Components
-#################################
-
-Use the chapters in this section to create advanced course components.
-
-.. toctree::
-   :maxdepth: 2
-
-   annotation
-   lti_component
-   open_response_assessment
-   word_cloud
\ No newline at end of file
diff --git a/docs/en_us/olx/source/components/discussion-components.rst b/docs/en_us/olx/source/components/discussion-components.rst
index a5fa05fbfd..183d1b2256 100644
--- a/docs/en_us/olx/source/components/discussion-components.rst
+++ b/docs/en_us/olx/source/components/discussion-components.rst
@@ -2,7 +2,7 @@
 Discussion Components
 #################################
 
-You can add inline discussion components to a vertical, or unit, in your
+You can add inline discussion components to any container in your
 course.
 
 See:
@@ -22,13 +22,26 @@ discussion component in your course.
 The name of the XML file must match the value of the @url_name attribute of the
 ``discussion`` element in the vertical XML file.
 
-For example, if the vertical XML file contains:
+In-line, you can create, if the vertical XML file contains:
 
 .. code-block:: xml
   
    <vertical display_name="Lesson_1_Unit_1">
-      <discussion url_name="Introduce_Yourself"/>
-      . . .
+      <discussion 
+          discussion_category="Essays" 
+          discussion_id="peer_grading_component" 
+          discussion_target="Peer Grading" 
+          display_name="Peer Grading"
+	  url_name="peer_grading_discussion"
+       /> 
+  </vertical>
+
+If you prefer to split this up, you can also create: 
+
+   <vertical display_name="Lesson_1_Unit_1">
+      <discussion 
+	  url_name="Introduce_Yourself"
+       /> 
   </vertical>
 
 You create the file ``discussion/Introduce_Yourself.xml`` to define the inline
diff --git a/docs/en_us/olx/source/components/html-components.rst b/docs/en_us/olx/source/components/html-components.rst
index e562da30ed..5680cdd3bd 100644
--- a/docs/en_us/olx/source/components/html-components.rst
+++ b/docs/en_us/olx/source/components/html-components.rst
@@ -4,7 +4,12 @@
 HTML Components
 #################################
 
-To add an HTML component to your course, you create both XML and HTML files.
+To add an HTML component to your course, you can either in-line it in
+the parent XML file, or split it up into either 1 or 2 additional
+files. HTML configuration can be broken out into a .xml file in the
+html directory. In addition, HTML content can be broken out into an
+additional .html file in the same directory. Breaking out HTML content
+is especially useful if you are embedding HTML which is not valid XML. 
 
 See:
 
@@ -15,11 +20,20 @@ See:
 * `Create the HTML File for an HTML Component`_
 * `Example HTML Component Content`_
 
+*************************************
+In-line HTML Example
+*************************************
+
+.. code-block:: xml
   
-Both files, for each component, must be in the ``html`` directory.
+   <vertical display_name="Lesson_1_Unit_1">
+      ...
+      <html>The above has an error. <b>x</b> should be <b>y</b> in the second equation.</html>
+  </vertical>
+
 
 *********************************************
-Create the XML File for an HTML Component
+Fully split HTML file example and explanation
 *********************************************
 
 You create an XML file in the ``html`` directory for each HTML component in your course.
@@ -43,7 +57,7 @@ HTML Component XML File Elements
 
 The root element of the XML file for the HTML component is file is ``html``. 
 
-The ``html`` element contains not children.
+In this case, the ``html`` element contains no children.
 
 *************************************
 ``html`` Element Attributes
@@ -113,5 +127,3 @@ file for the edX Demo course:
     &nbsp;They&rsquo;re fun to play with. &nbsp;Many courses will have tools
     and labs that you need to use to complete homework assignments.</p>
 
-
-
diff --git a/docs/en_us/olx/source/components/index.rst b/docs/en_us/olx/source/components/index.rst
index 3b6b2b966a..af139f2e10 100644
--- a/docs/en_us/olx/source/components/index.rst
+++ b/docs/en_us/olx/source/components/index.rst
@@ -1,10 +1,10 @@
 .. _Course Components:
 
 #################################
-Course Components
+Course Components (XBlocks)
 #################################
 
-Use the chapters in this section to create course components.
+Use the chapters in this section to create course components. 
 
 .. toctree::
    :maxdepth: 2
@@ -12,3 +12,14 @@ Use the chapters in this section to create course components.
    html-components
    discussion-components
    video-components
+   annotation
+   lti_component
+   open_response_assessment
+   word_cloud
+   conditional_module
+   full_screen_image
+   google_hangout
+   periodic_table
+   poll
+   vitalsource
+   zooming_image
diff --git a/docs/en_us/olx/source/components/video-components.rst b/docs/en_us/olx/source/components/video-components.rst
index 0d8c890095..d6e4c969f5 100644
--- a/docs/en_us/olx/source/components/video-components.rst
+++ b/docs/en_us/olx/source/components/video-components.rst
@@ -4,7 +4,9 @@
 Video Components
 #################################
 
-You can add video components to a vertical, or unit, in your course.
+You can add video components to any container in your course (such as
+a vertical or sequential). Studio places all video components inside
+verticals (which it calls units). 
 
 See:
 
@@ -17,8 +19,18 @@ See:
 Create the XML File for a Video Component
 **********************************************
 
-You create an XML file in the ``video`` directory for each video component in
-your course.
+If you wish to place a video in your course, add it to the course XML tree as: 
+
+  <video 
+    youtube="1.00:o2pLltkrhGM" 
+    url_name="Introduction_Lecture" 
+    display_name="Introduction Lecture" 
+    youtube_id_1_0="o2pLltkrhGM" 
+  </video>
+
+If you would prefer to break this out into its own file, you create an
+XML file in the ``video`` directory for each video component in your
+course.
 
 The name of the XML file must match the value of the @url_name attribute of the
 ``video`` element in the vertical XML file.
diff --git a/docs/en_us/olx/source/directory-structure.rst b/docs/en_us/olx/source/directory-structure.rst
index 6905767a5c..39200be3fc 100644
--- a/docs/en_us/olx/source/directory-structure.rst
+++ b/docs/en_us/olx/source/directory-structure.rst
@@ -1,7 +1,7 @@
 .. _ODL Directory Structure with edX Studio:
 
 ###############################################
-OLX Directory Structure
+OLX Course Structure
 ###############################################
 
 See:
@@ -17,8 +17,6 @@ See:
 * `tabs Directory`_
 * `video Directory`_
 
-
-
 ****************************************
 OLX and Directory File Structures
 ****************************************
@@ -26,26 +24,27 @@ OLX and Directory File Structures
 All files and sub-directories that comprise your OLX course are stored within
 a single directory.
 
-OLX provides for flexibility in the directory and file structure you use to
-build your course.
+OLX provides for some flexibility in the directory and file structure
+you use to build your course.
 
 ************************
 Top-level Directory
 ************************
 
-In most cases, it is easiest to create your courseware structure in a
-single file, the ``course.xml file``. 
+Starting out, it is easiest to create your courseware structure in a
+single file, the ``course.xml file``. This file may contain your
+entire course, but in most cases, it is convenient to split out large
+chunks of content into individual files. This is typically done either
+at the level of large components, such as either problems or homework
+assignments. 
 
-The ``course.xml`` file would contain the
-definition of all chapters (sections), sequentials (subsections), and verticals
-(units) in your courseware. The courseware structure would then refer to files
-for components, which are stored in a directory for each type of XBlock.
+Currently, Studio, on export, places each component in its own
+file. MIT ODL and edX have scripts which rechunk the file structure in
+different ways.
 
-For example, the edX Platform contains a directory called `manual-testing-complete`_ that contains a course with all component types for testing
-purposes.
-
-Course content, other than the courseware, is stored in separate directories
-and files as shown in the rest of this chapter.
+For example, the edX Platform contains a directory called
+`manual-testing-complete`_ that contains a course with all component
+types for testing purposes.
 
 Following are descriptions of directories needed for a typical course. You
 should set up these directories in preparation for developing your course
@@ -56,9 +55,40 @@ content.
  additional directories that store the XML for XBlocks of that type.
 
 ********************
-``about`` Directory
+XBlock directories (``html``, ``problem``, etc.)
 ********************
 
+edX course components may be broken out of the main course.xml file
+into individual files. Those files go into directories of the name of
+the component type (XML tag). For example, components of type ``html``
+may be placed as individual files in the ``html`` directory. If your
+course does not contain html files, or if they are all in-lined in
+their top-level components, you do not need to create an ``html``
+directory.
+
+For information about several examplars of these directories, see: 
+
+See :ref:`HTML Components` for more information.
+See :ref:`Problems and Tools` for more information.
+See :ref:`Video Components` for more information.
+
+As the set of XBlocks grows, so does the set of associated XML tags
+and directories.
+
+********************
+edX Platform Directories
+********************
+
+In addition to the course hierarchy, which is designed to be generic
+and cross-platform, XML course exports contain a set of JSON and HTML
+files providing edX-specific course metadata (such as course
+information pages specific to a MOOC setting), as well as things which
+have not yet been folded into the above framework.
+
+====================
+``about`` Directory
+====================
+
 The ``about`` directory contains:
 
 * ``overview.html``, which contains the content for the course overview page
@@ -70,21 +100,9 @@ The ``about`` directory contains:
 See :ref:`The Course About Pages` for more information.
 
 
-********************
-``html`` Directory
-********************
-
-The ``html`` directory contains an HTML file for each HTML component in
-the course.
-
-If you do not need HTML components in the course, you do not need to create
-this directory.
-
-See :ref:`HTML Components` for more information.
-
-********************
+====================
 ``info`` Directory
-********************
+====================
 
 The ``info`` directory contains:
 
@@ -94,9 +112,9 @@ The ``info`` directory contains:
 * ``updates.html``, which contains the course updates students see when opening
   a course.
 
-***********************
+====================
 ``policies`` Directory
-***********************
+====================
 
 The ``policies`` directory contains:
 
@@ -109,46 +127,22 @@ The ``policies`` directory contains:
   
 See :ref:`Course Policies` for more information.
 
-**********************
-``problem`` Directory
-**********************
-
-The ``problem`` directory contains an XML file for each problem component you
-use in your course.
-
-If you do not need problem components in the course, you do not need to create
-this directory.
-
-See :ref:`Problems and Tools` for more information.
-
-********************
+====================
 ``static`` Directory
-********************
+====================
 
 The ``static`` directory contains the files used in your course, such as images
 or PDFs.
 
 See :ref:`Course Assets` for more information.
 
-********************
+====================
 ``tabs`` Directory
-********************
+====================
 
 The ``tabs`` directory contains an HTML file for each page you add to your
 course.
 
 See :ref:`Course Pages` for more information.
 
-********************
-``video`` Directory
-********************
-
-The ``video`` directory contains an XML file for each video component you use
-in your course.
-
-If you do not need video components in the course, you do not need to create
-this directory.
-
-See :ref:`Video Components` for more information.
-
- .. include:: links.rst
\ No newline at end of file
+ .. include:: links.rst
diff --git a/docs/en_us/olx/source/index.rst b/docs/en_us/olx/source/index.rst
index 11dd3aa009..1a5a1850e3 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
-   advanced-components/index
    drafts/index
    demo-course/index
 
 
- 
\ 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 582e5cd5c9..ce3ed33162 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
@@ -16,19 +16,19 @@ Courseware
 Courseware is the main content of your course, namely lessons and assessments.
 The following list describes how courseware is organized in OLX:
 
-* Course sections are at the top level of your course and typically represent a
-  time period. In OLX, sections are represented by ``chapter`` elements. 
+* 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 subsections. Course subsections are parts of a
-  section, and usually represent a topic or other organizing principle. In
-  OLX, subsections are represented by ``sequential`` elements. 
+* A section contains one or more children which correspond to
+  top-level pages in the course. Studio calls these 'subsections' and
+  is currently restricted to ``sequential`` elements at this
+  level. OLX supports any XBlock at this level. 
 
-* A subsection contains one or more units. In OLX, units are represented by
-  ``vertical`` elements.  
-
-* Course units are lessons in a subsection that students view as single pages.
-  A unit contains one or more components. Course components are objects within
-  units that contain your actual course content. For more information, see:
+* Courses are composed of structural elements, such as ``sequential``
+  and ``vertical``, and leaf-nodes or content elements, such as
+  ``html`` or ``problem``. Studio has a fixed hierarchy where children
+  of ``sequential`` elements are ``vertical`` elements (called units),
+  and children of ``vertical`` elements are leaf elements (called modules). 
 
   * :ref:`Course Components`
   * :ref:`Problems and Tools`
@@ -61,4 +61,4 @@ Course Policies
 
 Course policies determine how your course functions. For example, policies
 control grading and content experiments. For more information, see
-:ref:`Policies`.
\ No newline at end of file
+:ref:`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 65569d34f2..951d31f8ca 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
@@ -20,8 +20,6 @@ The ``course.xml`` File
 
 The root element of the ``course.xml`` file is ``course``. 
 
-The ``course`` element does not contain any child elements.
-
 For example, the ``course.xml`` file may contain:
 
 .. code-block:: xml
@@ -82,7 +80,7 @@ For example:
 Course Chapters
 *******************************
 
-You create a course chapter with the ``chapter`` element, as a child of the root ``course`` element. 
+You create a course chapter with the ``chapter`` element, as a child of the root ``course`` element. Chapter elements are top-level pages in the course. The edX platform renders navigation chrome around them (tab-set on top and accordion on the left). It is possible to disable chrome for specific chapters using the ``chrome`` option. It is possible to associate chapters with different elements of the tabset with the ``default_tab`` option. It is possible to hide them from the navigation using the ``hide_from_toc`` option. 
 
 For example, if the course outline file contains:
 
@@ -114,10 +112,7 @@ For example, if the course outline file contains:
 ``chapter`` Children
 =========================
 
-The ``chapter`` element contains one or more child ``sequential`` elements. 
-
-The ``sequential`` element references a sequential, or subsection, in the
-course.
+The ``chapter`` element contains one or more children. Studio uses ``sequential`` elements for all children of chapters, and calls these ``subsections``.
 
 The following example shows a chapter with two sequentials, or subsections. :
 
diff --git a/docs/en_us/olx/source/pages/pages.rst b/docs/en_us/olx/source/pages/pages.rst
index 3c541b47a9..0858dd6511 100644
--- a/docs/en_us/olx/source/pages/pages.rst
+++ b/docs/en_us/olx/source/pages/pages.rst
@@ -4,7 +4,7 @@
 Course Pages
 #################################
 
-You can add pages to your course. Each page appears in your course’s navigation
+You can add tabs to your course. Each tab appears in your course’s navigation
 bar.
 
 *********************************************
@@ -14,4 +14,7 @@ Create the Page File
 You create an HTML file for each page you want to add to the course in the
 ``tabs`` directory.
 
-You can add any text and HTML markup to the page.
\ No newline at end of file
+You can add any text and HTML markup to the page. Tabs can also be
+links, and other types of content. One common design pattern is to
+link a tab to a chromeless XBlock in the courseware, which allows for
+top-level interactive course content.
diff --git a/docs/en_us/olx/source/problem-xml/index.rst b/docs/en_us/olx/source/problem-xml/index.rst
index ef6fe52ee5..c09f8f048b 100644
--- a/docs/en_us/olx/source/problem-xml/index.rst
+++ b/docs/en_us/olx/source/problem-xml/index.rst
@@ -1,10 +1,23 @@
 .. _Problems and Tools:
 
 #################################
-Problems and Tools
+Problems
 #################################
 
-Use the chapters in this section to create course problems and tools.
+The format for edX problems is based on the LONCAPA XML format (https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro), although the two are not quite compatible. In the edX variant, problems are composed of four types of tags: 
+
+* inputtypes are similar to XBlocks. They define ways for users to enter input into the problem. 
+* responsetypes are graders. They define how inputs are mapped to grades. 
+* hinters are used to provide feedback to problems. 
+* Standard HTML tags are used for formatting. 
+
+In abstract, the system is designed to allow mixing-and-matching of inputtypes, responsetypes, and hinters. For example, a numerical grader could match 7+-0.1%. It would be okay to use this with any inputtype which output a number, whether this was a text box, equation input, slider, or multiple choice question. In practice, this doesn't always work. For example, in the former case, a multiple choice question would not give an output in a format a numerical grader could handle. 
+
+In addition, in many cases, there is a 1:1 mapping between graders and inputs. For some types of inputs (especially discipline-specific specialized ones), it simply does not make sense to have more than one grader. 
+
+The most general grader is customresponse. This uses a piece of Python code to evaluate the input. By design, this ought to work with any inputtype, although there are bugs mixing this with a small number of the newer inputtypes. 
+
+Like LON-CAPA, OLX allows embedding of code to generate parameterized problems. Unlike LON-CAPA, edX supports Python (and not Perl). Otherwise, the syntax is approximately identical. 
 
 .. toctree::
    :maxdepth: 2
@@ -12,16 +25,11 @@ Use the chapters in this section to create course problems and tools.
    checkbox
    chemical_equation
    circuit_schematic_builder
-   conditional_module
    custom_javascript
    custom_python
    drag_and_drop
    dropdown
-   full_screen_image
    gene_explorer
-   google_hangout
-   graphical_slider_tool
-   iframe
    image_mapped_input
    math_expression_input
    mathjax
@@ -29,12 +37,8 @@ Use the chapters in this section to create course problems and tools.
    mult_choice_num_input
    multiple_choice
    numerical_input
-   periodic_table
-   poll
    problem_in_latex
    problem_with_hint
    protein_builder
    symbolic_response
    text_input
-   vitalsource
-   zooming_image
\ No newline at end of file