Directory structure revision

1 reply [Last post]
shaffer
shaffer's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 2019

This is a warning to developers (especially Tom’s students) that I am soon going to take the first step in the process of restructuring the AV directory. This means that the relative positions of the files will move around, perhaps requiring you to make some modifications to adapt.

Eventually, the various files will migrate to subdirectories in a "chapter" organization. For this first step, in essence nearly all files will be moved to a subdirectory with a name like "Development". The idea is that AVs and exercises under development will remain in that directory until they are pretty well complete and I have had a chance to vet them. At which point they would be moved to the appropriate "chapter" subdirectory depending on their topic.

Some prerequisites before something is ready to move out of the Development directory:

* CSS should be in a separate file (with .css suffix)

* JavaScript should be in a separate file (with .js suffix)

CSS should pass validation with csslint (see toward the end of OpenDSA/Makefile to see the right options to use)

* JavaScript should pass validation with jshint (using the configuration file at OpenDSA/.jshintrc)

Of course, those are just the mechanical prerquisites. A thorough usability review and code review should also be done. If you are a developer and you think that you have code that is "done", contact me so that I can go over the code with you.

 

shaffer
shaffer's picture
Offline
White BeltYellow BeltGreen BeltRed BeltBlack Belt
Joined: 2009-05-28
Posts:
Points: 2019
Re: Directory structure revision

I am currently making the changes, detailed below. This will involve a massive restructuring of the content files — nearly every one will move, and many will have their names changed. I hope to have the initial round in place by the end of today.

IF YOU ARE AN ACTIVE CONTENT DEVELOPER, YOUR FILE NAMES AND FILE PLACEMENT WILL CHANGE!

Content materials come in the form of modules, exercises, AVs, etc. There are various top-level directories, as explained below. Within each, the materials are subdivided into subdirectories based on topical content (such as Sorting). These content subdirectories are mirrored across all of the materials subtypes. That is, if there is a Sorting subdirectory in the AVs directory, there should also be one in the Exercises directory and the SourceCode directory to match. Note that the RST/source directory does not have such subdivisions at this time. In addition, each of the major top-level directories contains a subdirectory named Development. All code starts life in the Development subdirectory. Once it is completed, polished, validated, and had a thorough code review, Dr. Shaffer will move code out of the Development subdirectory to an appropriate content subdirectory.

Algorithm visualizations, proficiency exercises, and related code live in the AV directory.

Exercises built using the Khan Academy exercise infrastructure lives in the Exercises directory.

Tutorial modules live in the RST directory, with the actual source in RST/source.

Code examples that will be presented within the modules (such as Processing or Python code) lives in the SourceCode directory.

Generally, ReStructuredText module filenames begin with an uppercase letter, and other content filenames begin with a lowercase letter.

Individual files are further labeled by functional type. Files related to AVs have their filename end in AV (such as insertionsortAV.js). Files related to proficiency exercises end in PE. Files related to mini-slideshows or similar content that is included within a module end in CON. Khan Academy exercises that are multiple choice questions end in MC, and T/F questions end in TF. KA-based questions that are interactive (for example, where a user clicks on JSAV array elements to give an answer) end in INT. The practice is to put individual questions in separate files, and often these are then aggregated to present to students as a battery of "summary" questions. Such aggregations end in SUM.