edx/edx-platform — pull request #5525 by pmitros (2014-10-08 18:32:11+00:00)
Title: First pass at improving OLX docs

@mhoeber @cpennington This is a first pass at fixing some of the issues with OLX documentation. Changes:

* Correctly documents OLX structure, both with regards to course hierarchy and with regards to how directories are structured. Does not assume either a Studio layout or an all-in-one-file layout. Does not assume children have to have fixed format.
* Provides some minimal high-level documentation on the structure of OLX.
* Breaks up components between those which go in problem (inputtypes, responsetypes, etc.) and those which go in the top-level XML (XBlocks in course.xml). Right now, these were mixed.
* I don't assume the only possible types of XBlocks are HTML, Problem, and Video.

Potential issues with PR:

* I do not know RST very well. I did not confirm all docs were valid .rst. I edited in emacs. It would be good to confirm this.
* I did this fairly quickly. Copy-edit would be very helpful. I'm sure there are issues.

Unresolved in this PR:

* We need much more high level documentation about the overall structure of OLX. This jumps into details before giving a framework for thinking about OLX. I believe myself, Cale, Ned, and Dave are the people who could write or explain this.
* We need clear examples.
* Youtube documentation is confusing. Studio exports include redundant information. We need to figure out which of the two is required.