OpenDSA Active-eBook Project - Recent changes [en]

The OpenDSA Developer's Getting Started Guide

2012-05-17T19:57:05Z

Stable and Developer Versions:

← Older revision		Revision as of 19:57, 17 May 2012
(2 intermediate revisions by one user not shown)
Line 19:		Line 19:
	You can see a mirror for all of these repositories, and any files mentioned below, at http://algoviz.org/OpenDSA. For example, http://algoviz.org/OpenDSA/JSAV will mirror the JSAV stable release, http://algoviz/OpenDSA/build will mirror the built version of the modules, and so on.		You can see a mirror for all of these repositories, and any files mentioned below, at http://algoviz.org/OpenDSA. For example, http://algoviz.org/OpenDSA/JSAV will mirror the JSAV stable release, http://algoviz/OpenDSA/build will mirror the built version of the modules, and so on.

−	==Stable and ~~Developer Versions~~==	+	==Stable vs. Development Repositories and Official Mirrors==

	The repositories listed in the previous section are developer versions. We also maintain "stable" releases at SourceForge. The stable release is mirrored at: http://algoviz.org/OpenDSA/. Going to that URL will show you the OpenDSA project homepage, but any of the subdirectories (such as AV, Exercises, build, and JAV) will let you see the directory structure for the subdirectory.		The repositories listed in the previous section are developer versions. We also maintain "stable" releases at SourceForge. The stable release is mirrored at: http://algoviz.org/OpenDSA/. Going to that URL will show you the OpenDSA project homepage, but any of the subdirectories (such as AV, Exercises, build, and JAV) will let you see the directory structure for the subdirectory.
Line 35:		Line 35:
	==Module Development==		==Module Development==

−	~~[NOTE: THIS SECTION WILL SOON BE OBSOLETE AND REPLACED. WE ARE MOVING TO USING reStructuredText FOR MODULE DEVELOPMENT.]~~ Modules ~~currently reside at~~ OpenDSA~~/Modules. Module~~ files ~~end in~~ the ~~.odsa~~ suffix. ~~.odsa files~~ are ~~an XML format only slightly altered from~~ HTML by the ~~addition of our custom ODSA tags. Module files are converted to HTML files by OMP (OpenDSA Module Preprocessor). OMP is a python script~~. You can easily convert all of the existing modules to HTML files by running "make" from the ~~OpenDSA top-level~~ directory. Thus, the full workflow will typically require that you install the following on your machine:	+	Modules for OpenDSA are written in reStructuredText (and thus module files use the suffix .rst), and are compiled into HTML files using the Sphinx compiler. You can easily convert all of the existing modules to HTML files by running "make" from the RST directory. Thus, the full workflow will typically require that you install the following on your machine:
	* git		* git
−	* python 2.7 (NOT Python 3.x, we do not support that)
	* make (You can get GNU make for Windows at http://gnuwin32.sourceforge.net/packages/make.htm)		* make (You can get GNU make for Windows at http://gnuwin32.sourceforge.net/packages/make.htm)
		+	* python 2.7 (NOT Python 3.x, we do not support that). Note that I had some trouble with Python 2.7.3 64-bit version on Windows. When I tried to install setuptools, it wouldn't recognize that a Python installation was available. I had to re-install the 32-bit version.
		+	* Python setuptools to use easy_install for installing Sphinx. I think this is automatically a part of Python on Linux. For Windows, see http://pypi.python.org/pypi/setuptools#files. You will need to put [PythonHome]/Scripts onto your path, both for setuptools and for sphinx.
		+	* Sphinx (http://sphinx.pocoo.org/): With Python and setuptools installed, just type "easy_install sphinx" at the command line.

−	Documentation for ~~OMP~~ and ~~the ODSA tags~~ can be found at ~~OpenDSA~~/~~Doc~~/~~ModuleAuthoring~~.html	+	Documentation for using Sphinx and reStructuredText can be found at http://sphinx.pocoo.org/contents.html.

	==Exercise Development==		==Exercise Development==

JSAV Roadmap

2012-05-15T22:31:57Z

← Older revision		Revision as of 22:31, 15 May 2012
(2 intermediate revisions by one user not shown)
Line 83:		Line 83:
	* Added easier way to attach event handlers to the data structures		* Added easier way to attach event handlers to the data structures
	* Fixed a bug in array and tree value handling		* Fixed a bug in array and tree value handling
		+
		+	(Version 0.4.3 was posted to SourceForge on May 15, 2012)
		+
		+	* new features:
		+	** absolute positioning of labels, variables and data structures is now possible
		+	** labels can be attached to edges
		+	** displayInit() for controlling initial screen in slideshows
		+	* bug fixes:
		+	** issue with changing array value in horizontal layout in Webkit based browsers fixed
		+	** show/hide bug for data structures fixed
		+	* new minor features:
		+	** allow custom event binding for data structures
		+	** allow data to be passed to event handlers for data structures
		+	** added function JSAV.utils.rand.sample to get a random sample from an array

	<hr/>		<hr/>


−	Version 0.5: [The '''linked list''' release]	+	Version 0.5: [The '''linked list''' release] (ETA: June 2012)
	'''Driving activity: Linked list display, Open Hashing, Radix Sort''']		'''Driving activity: Linked list display, Open Hashing, Radix Sort''']
	* Support for drawing arrows with attached labels		* Support for drawing arrows with attached labels

Research Questions

2012-05-14T21:19:55Z

Created page with "Here is a list of research questions that we would like to address over the course of our project. * Hypothesis to test: Greatly increasing the amount of practice exercises comb..."

New page

Here is a list of research questions that we would like to address over the course of our project.

* Hypothesis to test: Greatly increasing the amount of practice exercises combined with immediate feedback through automated assessment will significantly improve learning in DSA courses.
* How can we significantly increase the students’ proficiencies with the core DSA material?
* Does an eTextbook help all students, or does it differentially support certain types of students?
* How can an eTextbook provide a steady stream of feedback to students about their knowledge?
* What are successful techniques to ensure that students properly engage the questions/activities, rather than guess or otherwise try to avoid doing them?
* How do we provide questions with a frequency that engages and informs, without becoming
tedious?
* How do we deal with procrastination when the primary content is online and students work at their own pace?
* How do we appropriately measure student gains in understanding of content? Students might
complete modules, but that alone does not guarantee improved learning.
* How do we balance out-of-class and in-class deployment of an active eTextbook? What is the role of the instructor in this situation?

Main Page

2012-05-14T21:11:08Z

← Older revision		Revision as of 21:11, 14 May 2012
Line 9:		Line 9:
	*[[Project Management]]		*[[Project Management]]
	*[[Learning Theory]]: A discussion of education theory and key papers relevant to the OpenDSA project		*[[Learning Theory]]: A discussion of education theory and key papers relevant to the OpenDSA project
		+	*[[Research Questions]]: Theoretical issues that we would like to address over the course of our project
	*[[What do we call this thing?]]		*[[What do we call this thing?]]
	*[[Directory Structure]]		*[[Directory Structure]]

Learning Theory

2012-05-14T01:13:51Z

Cognitive Theory of Multimedia Presentation:

← Older revision		Revision as of 01:13, 14 May 2012
(2 intermediate revisions by one user not shown)
Line 27:		Line 27:
	D.G. Oblinger and B.L. Hawkins, [http://net.educause.edu/ir/library/pdf/erm0667.pdf The Myth about No Significant Difference], ''EDUCAUSE Review'', Nov/Dec 2006, 14-15.		D.G. Oblinger and B.L. Hawkins, [http://net.educause.edu/ir/library/pdf/erm0667.pdf The Myth about No Significant Difference], ''EDUCAUSE Review'', Nov/Dec 2006, 14-15.

−	The appropriate message to take away from this research is '''not''' that technology is irrelevant. The truth is a bit more subtle. The key message is that, if you want to do the same thing as you did before, then a different technology is probably not going to make much difference. However, different technologies enable different capabilities to different degrees. This is referred to as an "affordance". For example, if all you want to do is read your textbook, an eReader isn't going to have much impact on learning as compared to a paper textbook. However, the eReader can enable a number of changes that might make a significant difference, such as greater access to the textbook content a times an places unavailable with the paper textbook, enhanced ability to ~~mark~~ notes, and improved search ability. Affordances can affect other aspects of the situation. A farfetched example, but useful to illustrate the concept: Putting all of one's textbooks on an eReader will greatly reduce the weight in a student's backpack, perhaps ultimately leading to better health.	+	The appropriate message to take away from this research is '''not''' that technology is irrelevant. The truth is a bit more subtle. The key message is that, if you want to do the same thing as you did before, then a different technology is probably not going to make much difference. However, different technologies enable different capabilities to different degrees. This is referred to as an "affordance". For example, if all you want to do is read your textbook, an eReader isn't going to have much impact on learning as compared to a paper textbook. However, the eReader can enable a number of changes that might make a significant difference, such as greater access to the textbook content at times and places unavailable with the paper textbook, enhanced ability to make notes in the textbook, and improved search ability. Affordances can affect other aspects of the situation. A farfetched example, but useful to illustrate the concept: Putting all of one's textbooks on an eReader will greatly reduce the weight in a student's backpack, perhaps ultimately leading to better health if it stops damaging their posture, or worse health if it gives them less exercise.

−	What is important here with respect to OpenDSA is to recognize that the goal is not to recreate old textbooks on an eReader, and not even just to make textbooks clearer by replacing static images with dynamic AVs. By providing interactive exercises with automated assessment, it is possible to introduce students to a huge increase in practice and feedback. This is an example of a new affordance of the active eTextbook that could have a huge impact.	+	What is important here with respect to OpenDSA is to recognize that the goal is not to recreate old textbooks on an eReader, and not even just to make textbooks clearer by replacing static images with dynamic AVs. By providing interactive exercises with automated assessment, it is possible to introduce students to a huge increase in practice and feedback. This is an example of a new affordance enabled by the active eTextbook that could have a huge impact.

	==Learning Styles==		==Learning Styles==
Line 47:		Line 47:
	The following are a number of principles (each validated by numerous research studies confirming the associated principle) that I find particularly relevant to the OpenDSA project.		The following are a number of principles (each validated by numerous research studies confirming the associated principle) that I find particularly relevant to the OpenDSA project.

−	~~TODO~~: ~~Listing~~	+	The bottom line for us is that the research shows that, for tutorials like ours, audio narration linked to the on-screen visualizations is superior to text explaining the visualizations. There are also a lot of secondary results relevant to how we would implement our modules. Some speciﬁcs include:
		+
		+	*Do '''not''' add text duplicating the audio content. That turns out to be merely a distractor from the visualization.
		+	* Break the audio segments into very short (a few seconds) clips, so that the student can process what they heard. So for example, just as we decided that the Shellsort module should have text interspersed with short bits of slidehsow as opposed to one long slideshow, an audio implementation of this module should have a series of short audio clips, perhaps one for each bit of slideshow, instead of a single audio tutorial that is several minutes long.
		+	* Any text labels should appear immediately with what is being labeled, and not as a caption down below or otherwise separated from the graphic.
		+	* The style of presentation (whether audio narration or text) should be less formal, speaking in ﬁrst or second person directly from the narrator to the listener rather than more formal third person. Of course, most textbooks get this hopelessly wrong (not to mention academic research papers).

Main Page

2012-05-14T00:59:03Z

Index:

← Older revision		Revision as of 00:59, 14 May 2012
Line 8:		Line 8:
	* New developers should start with [[the OpenDSA Developer's Getting Started Guide]]		* New developers should start with [[the OpenDSA Developer's Getting Started Guide]]
	*[[Project Management]]		*[[Project Management]]
−	*[[~~Background Reading~~]]: A ~~brief listing~~ of ~~significant research~~ papers	+	*[[Learning Theory]]: A discussion of education theory and key papers relevant to the OpenDSA project
	*[[What do we call this thing?]]		*[[What do we call this thing?]]
	*[[Directory Structure]]		*[[Directory Structure]]
Line 16:		Line 16:
	*The [[JSAV Library]]		*The [[JSAV Library]]
	*The [[JSAV Roadmap]]		*The [[JSAV Roadmap]]
−	*[[Learning Theory]]
	*[[Organization and Modularity]]: How AVs and exercises are embedded into the content		*[[Organization and Modularity]]: How AVs and exercises are embedded into the content
	*[[Module Authoring Support]]		*[[Module Authoring Support]]

Learning Theory

2012-05-14T00:48:08Z

Cognitive Theory of Multimedia Presentation:

← Older revision		Revision as of 00:48, 14 May 2012
(5 intermediate revisions by one user not shown)
Line 1:		Line 1:
−	This page documents key results from the literature related to learning theory as it relates to OpenDSA.	+	This page documents key results from the literature related to learning theory as it relates to OpenDSA. Included in this discussion are links to some key papers. For a much more comprehensive list of research related to eTextbooks, see: http://people.cs.vt.edu/~shaffer/CS6604/Readings.php.
		+
		+	==The Algorithm Visualization Literature==
		+
		+	Here are the key standard papers from the Algorithm Visualization literature relating to learning theory.
		+
		+	C.D. Hundhausen, S.A. Douglas, and J.T. Stasko, [http://dx.doi.org/10.1006/jvlc.2002.0237 A Meta-Study of Algorithm Visualization Effectiveness], ''Journal of Visual Languages & Computing 13'', 3(June 2002), 259-290.
		+
		+	T.L. Naps, G. Rossling, et al., [http://dl.acm.org/citation.cfm?doid=960568.782998 Exploring the Role of Visualization and Engagement in computer science education], in ''Proceedings of ITiCSE-WGR '02 Working group reports from ITiCSE on Innovation and technology in computer science education'', 2002.
		+
		+	T.L. Naps, S. Cooper, et al., [http://dl.acm.org/citation.cfm?id=960540 Evaluating the Educational Impact of Visualization], in ''Proceedings of ITiCSE-WGR '03 Working group reports from ITiCSE on Innovation and technology in computer science education'', 2003.
		+
		+	Collectively, the results of these papers can be summed up by saying: AVs need to be interactive (and engage the student into doing something) to be effective.
		+
		+	I will also add the following paper to the list:
		+
		+	V. Karavirta, A. Korhonen, and L. Malmi, [http://aalto-fi.academia.edu/VilleKaravirta/Papers/534471/On_the_use_of_resubmissions_in_automatic_assessment_systems On the Use of Resubmissions in Automatic Assessment System], ''Computer Science Education'', 16(3), September 2006, 229-240.
		+
		+	This is useful because it discusses the practical issue of designing interactive activities so that students don't find it profitable to just guess the answers, which is often a problem in poorly designed courseware.
		+
		+	==No Significant Difference==
		+
		+	The term "No Significant Difference" refers to the overwhelming body of evidence (through literally hundreds of studies) that technology does not affect learning -- hence the idea that there is no significant difference between technologies. This study was first popularized by Thomas L. Russell's book by this name. The book is not available online, but here are two good papers that help to cover the major ground:
		+
		+	R.E. Clark and D.F. Feldon, [http://www.cogtech.usc.edu/publications/clark_five_common.pdf Five Common but Questionable Principles of Multimedia Learning] in ''Cambridge Handbook of Multimedia learning'', R. Mayer (ed), 2005.
		+
		+	D.G. Oblinger and B.L. Hawkins, [http://net.educause.edu/ir/library/pdf/erm0667.pdf The Myth about No Significant Difference], ''EDUCAUSE Review'', Nov/Dec 2006, 14-15.
		+
		+	The appropriate message to take away from this research is '''not''' that technology is irrelevant. The truth is a bit more subtle. The key message is that, if you want to do the same thing as you did before, then a different technology is probably not going to make much difference. However, different technologies enable different capabilities to different degrees. This is referred to as an "affordance". For example, if all you want to do is read your textbook, an eReader isn't going to have much impact on learning as compared to a paper textbook. However, the eReader can enable a number of changes that might make a significant difference, such as greater access to the textbook content a times an places unavailable with the paper textbook, enhanced ability to mark notes, and improved search ability. Affordances can affect other aspects of the situation. A farfetched example, but useful to illustrate the concept: Putting all of one's textbooks on an eReader will greatly reduce the weight in a student's backpack, perhaps ultimately leading to better health.
		+
		+	What is important here with respect to OpenDSA is to recognize that the goal is not to recreate old textbooks on an eReader, and not even just to make textbooks clearer by replacing static images with dynamic AVs. By providing interactive exercises with automated assessment, it is possible to introduce students to a huge increase in practice and feedback. This is an example of a new affordance of the active eTextbook that could have a huge impact.
		+
		+	==Learning Styles==
		+
		+	"Learning styles" theory begins with the appealing hypothesis that people are different in the ways that they learn, and therefore instructors should accommodate those differences. Most variations on Learning Styles theory will identify about 3-5 dichotomous scales, such as a preference for visual presentation vs. verbal presentation. There are two aspects to learning styles. First, there appears to be a sufficient body of evidence that students do in fact have consistent preferences for learning style. That is, one can survey students for their preference have it remain consistent. Second, there appears to be little evidence to support the idea that teaching in a style that matches the students' preference improves their learning, or that teaching in the opposing style harms their learning. In fact, there is a significant body of research demonstrating that the "meshing hypothesis" (the key notion that one should match instructional approach to learning style preference) has no support. The following paper summarizes these findings well.
		+
		+	Pashler, H. McDaniel, M. Rohrer, D. and Bjork, R., "[http://128.220.136.46/wiki/baderlab/images/9/9d/Pashler-psych-2008.pdf Learning styles concepts and evidence]", ''Psychological Science in the Public Interest'' 9, 3 (2008).
		+
		+	In my opinion, this result should not be surprising. Essentially, learning styles theory creates winners and losers. For it to have any practical effect (that is, for the meshing hypothesis to be true) means that whenever you help one group of students by accommodating their learning style preference, you must be hurting another group. This observation is generally not acknowledged by proponents of the theory. More importantly, it is a good thing for developers that learning styles theory can be safely ignored. It is difficult enough to build effective learning interventions. It would be far worse if we had to build multiple interventions to accommodate a range of styles. We can instead focus on trying to build the best possible intervention.
		+
		+	==Cognitive Theory of Multimedia Presentation==
		+
		+	The Cognitive Theory of Multimedia Presentation as advanced by Mayer and his colleagues is an extension of Cognitive Load theory of Sweller. The fundamental concept is that humans have limited bandwidth for absorbing information through their visual and auditory senses, but that there is some increase in the potential bandwidth available if one effectively fills both of those channels during the presentation. What makes this theory so attractive to me is that it provides many concrete and implementable proscriptions that can be tested. Thus, it leads to extremely practical results. Before I go into this in detail, I will mention that Hundhausen, et al's meta-study discusses this topic under the name "dual coding theory". They find in general that interaction (specifically, constructivist approaches) are the crucial determinant to success, and not adherence to dual coding theory. Personally, I do not see a contradiction. Clearly interaction is key, but the devil is in the details. Cognitive Theory helps one work through the tactics of one's presentation of content without contradicting the notion that one should have rich interaction. A good summary of Cognitive Theory and its practical application can be found in the following paper.
		+
		+	R.E. Mayer, [http://psycnet.apa.org/journals/amp/63/8/760.html Applying the Science of Learning: Evidence-Based Principles for the Design of Multimedia Instruction], ''American Psychologist'', 63(8), 760-769.
		+
		+	The following are a number of principles (each validated by numerous research studies confirming the associated principle) that I find particularly relevant to the OpenDSA project.
		+
		+	TODO: Listing

Background Reading

2012-05-14T00:06:21Z

← Older revision		Revision as of 00:06, 14 May 2012
(One intermediate revision by one user not shown)
Line 1:		Line 1:
−	~~A short reading list of some key papers. For a much more comprehensive list of research related to eTextbooks, see: http://people.cs.vt.edu/~shaffer/CS6604/Readings.php.~~	+	This page has been replaced by the one on [[Learning Theory]], and I will delete this one when I get to it.
−		+
−	# C.D. Hundhausen, S.A. Douglas, and J.T. Stasko, [http://dx.doi.org/10.1006/jvlc.2002.0237 A Meta-Study of Algorithm Visualization Effectiveness], ''Journal of Visual Languages & Computing 13'', 3(June 2002), 259-290.	+
−	~~# R.E. Mayer, [http://psycnet.apa.org/journals/amp/63/8/760.html Applying~~ the ~~Science of Learning: Evidence-Based Principles for the Design of Multimedia Instruction], ''American Psychologist'', 63(8), 760-769.~~	+
−	# V. Karavirta, A. Korhonen, and L. Malmi, [http://aalto-fi.academia.edu/VilleKaravirta/Papers/534471/On_the_use_of_resubmissions_in_automatic_assessment_systems On the Use of Resubmissions in Automatic Assessment System], ''Computer Science Education'', 16(3), September 2006, 229-240.	+
−	# T.L. Naps, G. Rossling, et al., [http://dl.acm.org/citation.cfm?doid=960568.782998 Exploring the Role of Visualization and Engagement in computer science education], in ''Proceedings of ITiCSE-WGR '02 Working group reports from ITiCSE on ~~Innovation and technology in computer science education'', 2002.~~	+
−	~~# T.L. Naps, S. Cooper, et al.,~~ [http://dl.acm.org/citation.cfm?id=960540 Evaluating the Educational Impact of Visualization], in ''Proceedings of ITiCSE-WGR '03 Working group reports from ITiCSE on Innovation and technology in computer science education'', 2003.	+
−	~~# R.E. Clark and D.F. Feldon,~~ [~~http://www.cogtech.usc.edu/publications/clark_five_common.pdf Five Common but Questionable Principles of Multimedia~~ Learning] ~~in ''Cambridge Handbook of Multimedia learning''~~, ~~R. Mayer (ed), 2005.~~	+
−	~~# D.G. Oblinger~~ and ~~B.L. Hawkins, [http://net.educause.edu/ir/library/pdf/erm0667.pdf The Myth about No Significant Difference], ''EDUCAUSE Review'', Nov/Dec 2006, 14-15~~.	+

Learning Theory

2012-05-13T23:53:30Z

Created page with "This page documents key results from the literature related to learning theory as it relates to OpenDSA."

New page

This page documents key results from the literature related to learning theory as it relates to OpenDSA.

Performance Tracking Infrastructure

2012-05-13T23:51:30Z

← Older revision		Revision as of 23:51, 13 May 2012
(2 intermediate revisions by one user not shown)
Line 1:		Line 1:
		+	This page is for discussing issues related to a major component of the ecosystem: How data are collected related to student performance (e.g., which modules or exercises a given student has completed). An example implementation that we are considering for our use is the Khan Academy "back end" infrastructure. take a look at http://www.khanacademy.org/about.

−	~~This page is for discussing issues related to~~ a ~~major component~~ of the ~~ecosystem: How data are collected related to student performance~~ (e.g., ~~which modules or exercises~~ a ~~given student has completed)~~. ~~An example implementation~~ that we ~~are considering for our~~ use is the ~~Khan Academy "back end" infrastructure~~.	+	We have installed the KA infrastructure and implemented a proof-of-concept re-skinning of the interface and done some initial testing (this resides on the algoviz-beta.cc.vt.edu machine at /home/algoviz-beta/OpenDSA/stableExp). We hope to get a reliable test server up and running on a consistent basis, but right now we only run it for temporary tests. When its up, it is available http://algoviz-beta.cc.vt.edu:8090.
		+
		+	Presently, a concern with the KA infrastructure is that it is implemented using Google App Engine. This would seem to imply that, if we want to use this, we would have to pay for Google Cloud hosting. There would also be FERPA issues with student data going off-site. One possible option for overcoming this is to use an alternate implementation for the GAE APIs. See http://code.google.com/p/appscale/, http://appscale.cs.ucsb.edu/appengine.html

Assessment Infrastructure

2012-05-13T23:43:11Z

← Older revision		Revision as of 23:43, 13 May 2012
Line 23:		Line 23:

	Would like to support questions of the nature "Give me a set of numbers that need 3 swaps to sort by insertion sort." A back-end evaluator would need to be tied to running the algorithm on the student's answer to verify correctness. This sort of thing is supported by the [git://github.com/Khan/khan-exercises.git Khan Academy infrastructure]. You can see examples of Khan Academy-style exercises that we have created [http://algoviz.org/OpenDSA/Exercises here].		Would like to support questions of the nature "Give me a set of numbers that need 3 swaps to sort by insertion sort." A back-end evaluator would need to be tied to running the algorithm on the student's answer to verify correctness. This sort of thing is supported by the [git://github.com/Khan/khan-exercises.git Khan Academy infrastructure]. You can see examples of Khan Academy-style exercises that we have created [http://algoviz.org/OpenDSA/Exercises here].
		+
		+	The folks at Connexions are working on a question bank system named QuadBase: http://quadbase.org.
		+
		+	Students at Virginia Tech have done an initial proof-of-concept implementation of a graphical front end for authoring questions (based on quadbase), but which can support templated questions and translation to Khan Academy-style question format. See http://algoviz-beta.cc.vt.edu/QBank.

Main Page

2012-05-13T23:40:29Z

Index:

← Older revision		Revision as of 23:40, 13 May 2012
Line 16:		Line 16:
	*The [[JSAV Library]]		*The [[JSAV Library]]
	*The [[JSAV Roadmap]]		*The [[JSAV Roadmap]]
		+	*[[Learning Theory]]
	*[[Organization and Modularity]]: How AVs and exercises are embedded into the content		*[[Organization and Modularity]]: How AVs and exercises are embedded into the content
	*[[Module Authoring Support]]		*[[Module Authoring Support]]

JSAV Roadmap

2012-05-13T23:38:00Z

← Older revision		Revision as of 23:38, 13 May 2012
Line 117:		Line 117:
	Wishlist, not currently scheduled:		Wishlist, not currently scheduled:
	* Key bindings for slideshow controls [But what do we do with multiple AVs on a page?]		* Key bindings for slideshow controls [But what do we do with multiple AVs on a page?]
−	* Position-based layout of UI objects [Not high priority since we can make do with HTML layout]

The OpenDSA Developer's Getting Started Guide

2012-05-13T02:40:46Z

Exercise Development:

← Older revision		Revision as of 02:40, 13 May 2012
(9 intermediate revisions by one user not shown)
Line 35:		Line 35:
	==Module Development==		==Module Development==

−	Modules currently reside at OpenDSA/Modules. Module files end in the .odsa suffix. .odsa files are an XML format only slightly altered from HTML by the addition of our custom ODSA tags. Module files are converted to HTML files by OMP (OpenDSA Module Preprocessor). OMP is a python script. You can easily convert all of the existing modules to HTML files by running "make" from the OpenDSA top-level directory. Thus, the full workflow will typically require that you install the following on your machine:	+	[NOTE: THIS SECTION WILL SOON BE OBSOLETE AND REPLACED. WE ARE MOVING TO USING reStructuredText FOR MODULE DEVELOPMENT.] Modules currently reside at OpenDSA/Modules. Module files end in the .odsa suffix. .odsa files are an XML format only slightly altered from HTML by the addition of our custom ODSA tags. Module files are converted to HTML files by OMP (OpenDSA Module Preprocessor). OMP is a python script. You can easily convert all of the existing modules to HTML files by running "make" from the OpenDSA top-level directory. Thus, the full workflow will typically require that you install the following on your machine:
	* git		* git
	* python 2.7 (NOT Python 3.x, we do not support that)		* python 2.7 (NOT Python 3.x, we do not support that)
Line 50:		Line 50:
	You should take a look at OpenDSA/Exercises for examples of exercises that we have written, including ones that use JSAV. You can also look at https://github.com/Khan/khan-exercises/wiki/Good-examples-and-pro-tips to see some examples, ideas, and tips from the developers at Khan Academy. You will need to read the documentation provided by Khan Academy (https://github.com/Khan/khan-exercises/wiki/Writing-Exercises:-Home).		You should take a look at OpenDSA/Exercises for examples of exercises that we have written, including ones that use JSAV. You can also look at https://github.com/Khan/khan-exercises/wiki/Good-examples-and-pro-tips to see some examples, ideas, and tips from the developers at Khan Academy. You will need to read the documentation provided by Khan Academy (https://github.com/Khan/khan-exercises/wiki/Writing-Exercises:-Home).

−	Note that you can view an exercise HTML page properly if it has been processed by a web server. If you just have a local file on your PC that you look at with your web browser (with no web server running), then you won't see much.	+	Note that you can view an exercise HTML page properly only if it has been processed by a web server. If you just have a local file on your PC that you look at with your web browser (with no web server running), then you won't see much. But there is a simple fix for this if you have Python installed. Look at ~OpenDSA/WebServer for how to run a simple local server in Python that you can use to do your testing.

−	We are beginning to investigate using Quadbase as a front end for exercise development (perhaps converting to KA-style format after creation). Quadbase is available at: https://github.com/lml/quadbase. This is implemented using Ruby-on-rails.	+	We are beginning to investigate using Quadbase as a front end for exercise development (perhaps converting to KA-style format after creation). Quadbase is available at: https://github.com/lml/quadbase. This is implemented using Ruby-on-rails. We are also working on our own graphical front end for editing questions and converting them to KA format. Take a look at http://algoviz-beta.cc.vt.edu/QBank.

	==AV Development==		==AV Development==

	We build our AVs with support from the JSAV development library. You can look at the various examples in the JSAV and OpenDSA repositories to help you get started. The documentation for JSAV is at JSAV/doc, which is mirrored at http://algoviz.org/OpenDSA/JSAV/doc. The JSAV API is documented at http://algoviz.org/OpenDSA/JSAV/doc/api.html, and there is a simple example of how to create a proficiency exercise at http://algoviz.org/OpenDSA/JSAV/doc/exercise.html. The official stable release version of JSAV can be linked to at http://algoviz.org/OpenDSA/JSAV/build/JSAV-min.js. If you need to use the development version of JSAV (most AV developers do not!), this is available at https://github.com/vkaravir/JSAV, mirrored at http://algoviz.org/OpenDSA/dev/OpenDSA/JSAV/build/JSAV-min.js		We build our AVs with support from the JSAV development library. You can look at the various examples in the JSAV and OpenDSA repositories to help you get started. The documentation for JSAV is at JSAV/doc, which is mirrored at http://algoviz.org/OpenDSA/JSAV/doc. The JSAV API is documented at http://algoviz.org/OpenDSA/JSAV/doc/api.html, and there is a simple example of how to create a proficiency exercise at http://algoviz.org/OpenDSA/JSAV/doc/exercise.html. The official stable release version of JSAV can be linked to at http://algoviz.org/OpenDSA/JSAV/build/JSAV-min.js. If you need to use the development version of JSAV (most AV developers do not!), this is available at https://github.com/vkaravir/JSAV, mirrored at http://algoviz.org/OpenDSA/dev/OpenDSA/JSAV/build/JSAV-min.js
		+
		+	Note: If you want to be able to compile JSAV (which you will need to do if you are installing the developer's version instead of pulling the library from the Internet), then you must have Java installed to run the JavaScript minimizer tool.

	==JavaScript (and other programming) Resources==		==JavaScript (and other programming) Resources==
Line 113:		Line 115:
	<tt>git commit</tt>		<tt>git commit</tt>

−	This will take you to an editor to add comments. '''Never commit anything to the repository without including a clear and concise comment about what you have changed!''' Also, ~~never do~~ "git commit -a" since that is sure to bring you to grief sometime with the relationships between the repository and its submodules. Best practice is to explicitly add each file that you have modified and that you intend to save. You can do multiple commits if you like. But the important thing to understand is that "git commit" does not save anything, it merely "stages" things locally. To actually move anything into GitHub so that others can see the changes, you must finish the process by using:	+	This will take you to an editor to add comments. '''Never commit anything to the repository without including a clear and concise comment about what you have changed!''' Also, avoid "git commit -a" since that is sure to bring you to grief sometime with the relationships between the repository and its submodules. Best practice is to explicitly add each file that you have modified and that you intend to save. If you feel that this is a burden because you think that you are having to add too many files by hand, then you are probably not committing frequently enough. You can do multiple commits if you like before a push. But the important thing to understand is that "git commit" does not save anything, it merely "stages" things locally. To actually move anything into GitHub so that others can see the changes, you must finish the process by using:

	<tt>git push</tt>		<tt>git push</tt>
Line 125:		Line 127:
	=="Front End" Development==		=="Front End" Development==

−	The "front end" refers to infrastructure that supports organizing and viewing collections of modules. ~~Related material~~ is ~~in OpenDSA/Frontend~~.	+	The "front end" refers to infrastructure that supports organizing and viewing collections of modules. Eric is working on this, and we need to get his work committed to a repository. Notes will be forthcoming.

	=="Back End" Development==		=="Back End" Development==
Line 145:		Line 147:
	* python-setuptools		* python-setuptools

		+	We have a version of this, modified to "skin" for OpenDSA, installed at /home/algoviz-beta/OpenDSA/stableExp.

	==Installing Tools on Windows==		==Installing Tools on Windows==
Line 152:		Line 155:
	On Windows, I have only tested GNU make, using the bash shell that comes with the Git distribution for my environment.		On Windows, I have only tested GNU make, using the bash shell that comes with the Git distribution for my environment.

−	You will need to be sure that Git, Python, and make are on your path.	+	You will need to be sure that Git, Python, Java, and make are on your path. On Windows 7, you edit your path variable by right-clicking your Computer icon, clicking on "Advanced system settings" and then "Environment Variables". If you have a 64-bit operating system, be aware that the various GNU tools will not work properly if they see "Program Files (x86)" on the system path variable. You might need to install these tools elsewhere, and/or reorder things on the path so that the GNU tool appears before anything referencing "Program Files (x86)".
−		+
−	If you have a 64-bit operating system, be aware that the various GNU tools will not work properly if they see "Program Files (x86)" on the system path variable. You might need to install these tools elsewhere, and/or reorder things on the path so that the GNU tool appears before anything referencing "Program Files (x86)".	+

−	Beware if you have Cygwin installed on your Windows machine~~, there~~ might be path conflicts ~~with~~ Git and the GNU tools.	+	Beware if you have Cygwin installed on your Windows machine: There might be path conflicts between Cygwin on the one hand, and the Git Shell and the GNU tools on the other. If you insist on trying to use both on your system, you are on your own. Otherwise you have two reasonable options:
		+	* If you don't use Cygwin much, then delete it entirely from your system. Or
		+	* Stick completely with using Cygwin, by running Git and your other tools from within it instead of the Git command shell.