Initial commit of API plan.

1 files changed, 155 insertions, 0 deletions

diff --git a/doc/quiz-api.rst b/doc/quiz-api.rst
new file mode 100644
index 0000000..b810e2b
--- /dev/null
+++ b/doc/quiz-api.rst
@@ -0,0 +1,155 @@
+.. vim:filetype=rst:tw=76:
+
+=================================
+Sugar Quiz API Preliminary Design
+=================================
+
+Motivation
+==========
+
+In the RIT class working on the Math4 projects, many proposed activities
+require a question database of some kind.  A common API or library for
+accessing databases in different formats, stored either locally or remotely,
+along with a simple mechanism to determine more complex formatting or
+presentation than simple text (e.g. to include simple graphics or
+mathematical notation) would cover a majority of the cases where the
+activity needs some configurable "curriculum data".
+
+Eventually this library could be extended to provide hints, explanations, or
+walkthroughs for questions, in addition to the basic metadata about level,
+grouping, difficulty, and subject matter that would be part of the base
+system.
+
+Envisioned Usage
+================
+
+Consider a simple flash-card-like activity.  It presents a question from a
+list of questions, allows the student to select an answer from the provided
+answers for the question or to enter their own answer.  Then the correct
+answer is revealed and the student it told whether their answer is correct.
+If the question has an explanation of the correct answer, the flash-card
+activity will show the explanation of the correct answer.  (Note that this
+is just a simple usage example, the interaction design of a drilling
+activity could be markedly different.)
+
+The flash-card activity would use this proposed Quiz API for the following:
+
+    - Loading the questions from the storage location into memory. This
+      includes any filtering or network lookup to download the questions
+      from a remote resource and select appropriate questions for the
+      student.
+
+    - Determining whether the student has entered a correct answer.
+
+    - Rendering the question to a simple widget/canvas. (i.e. pass the
+      library a GtkCanvas or similar and tell it to display the question)
+
+To start with, the library would simply be a time-saving tool for developers
+needing similar functionality, but as the XS (School Server) becomes more
+fully developed the library should integrate the functions provided by the
+XS to enable automated update of course material for the current topic of
+study so the students can drill material using any tool they prefer, while
+still reporting progress to the instructor using the XS services.
+
+Proposed API
+============
+
+The Quiz API would be a python library, to act mostly as glue between
+various file formats (and local or remote resources) for question data and
+the Gtk graphical environment, providing a simple way to consistently
+present and layout questions.
+
+    :quizdata.open(uri, [cache=False]):
+        Opens a URI, returning a list of quizdata.Question instances.  A
+        standard method of filtering question data based on parameters
+        should be specified.  Examples of URIs that might be used::
+
+            http://xs-server/math4class/current_topic?level=4&difficulty=hard&format=moodle
+
+            file:///var/lib/mathquestions/quiz1?level=4&difficulty=hard&format=xml
+
+            xmpp://teacheraccount@xs.server/classname?difficulty=hard&level=4
+
+        The cache parameter would locally save the retrieved questions to a
+        persistent storage so requests from the same URI (with cache=True)
+        would read from the cache.
+
+    :class quizdata.Question:
+        This class contains individual data for a question:
+            - The question text
+            - The style of answer (incl. multiple-choice, numeric, free
+              response, etc.)
+            - The correct answer (or if the question is subjective, that
+              there *is* no correct answer).
+            - Question difficulty
+            - Grade level
+            - Tags (for free-form grouping by topic, course, instructor,
+              etc.)
+
+        The question text and answers should support at least minimal
+        markup, like that supported by pango, in addition to markup
+        rendering with MathML/LaTeX syntax.
+
+        .. note:: 
+            The attributes listed above will should grow standardized names
+            and be documented as part of the interface to the Question
+            class, to allow for fine-grained for activity controlled
+            rendering of the Question, if the simple show() call is not
+            appropriate.
+
+        :Question.show(surface, x, y, [width=-1, [height=-1]]):
+            Draw the question to the drawing surface at coordinates (x,y)
+            limited to the optionally specified width/height.
+
+            This also should set up the appropriate input widgets for the
+            type of question (multiple-choice/free-response) and handle the
+            vents for those widgets.
+
+        :Question.answered():
+            Returns True if the student has provided an answer for the
+            Question.
+
+        :Question.submitted():
+            Returns True if the student has submitted an answer for the
+            Question.
+
+        :Question.correct():
+            Returns True if the currently selected answer is correct for the
+            Question.
+
+        :Question.answer():
+            Returns the answer the student has currently selected, or None
+            if no answer has been entered.
+
+        :Question.clear():
+            Removes the widgets and drawings that show() set up, preparing
+            the surface to receive the next question or other widgets.
+
+
+Implementation Issues
+======================
+
+The implementation of this (deceptively simple) library will take some
+effort, in that it will be closely tied to the windowing/graphical toolkit,
+PyGtk/Cairo/Pango rather directly, due to the high level of abstraction.
+Additionally the URI lookup and question filtering based on parameters will
+be necessary, as will interpreter the various format parsers necessary to
+build the Question objects.
+
+For MathML support, the GtkMathView widget will need to be available, so a
+certain amount of effort may be involved in packaging the library in a
+simple way for activity developers.
+
+Next Steps
+==========
+
+Firstly, this API is being proposed and posted to the Math4 mailing list for
+feedback and changes before any commitments to this interface is decided.
+For any activity developers who are currently working on an activity that
+could take advantage of such a system, or who have written similar
+functionality in an activity, your input on usage and the naturalness of the
+API.
+
+Secondly, anyone who is interested in doing work on this library or using
+the library in their activity should chime in, along with the expected usage
+or how you can contribute.