Converted SurveysModule.md
diff --git a/SurveysModule.wiki b/SurveysModule.md
similarity index 76%
rename from SurveysModule.wiki
rename to SurveysModule.md
index 21bdfba..3a20f09 100644
--- a/SurveysModule.wiki
+++ b/SurveysModule.md
@@ -1,19 +1,17 @@
-#summary Design/discussion for Surveys
-#labels Importance-Useful,Phase-Requirements,Contents-Draft
-<wiki:toc max_depth="3" />
-= GSoC Project Info =
+# GSoC Project Info
-|| James Levy || [http://socghop.appspot.com/student_project/show/google/gsoc2009/melange/t124022698643 Project description] ||
+| James Levy | [Project description](http://socghop.appspot.com/student_project/show/google/gsoc2009/melange/t124022698643) |
+|:-----------|:-------------------------------------------------------------------------------------------------------------|
-= Introduction =
+# Introduction
Surveys are used in GSoC for two general purposes:
-
- -General polling/survey (can be restricted to mentors, students, etc.)
- -Midterm/Final surveys for students and mentors associated with a certain program to take.
+> -General polling/survey (can be restricted to mentors, students, etc.)
+
+> -Midterm/Final surveys for students and mentors associated with a certain program to take.
Each year the questions asked change slightly.
@@ -28,62 +26,62 @@
* Ad-Hoc surveys
* Currently these are done using Google forms. In 2009 OSPO sent an additional survey to examine the relationship between numbers of student applications and quality.
-Surveys, or at least the techniques used to achieve them, could be used more widely to make existing Models extensible. Issue 520 and Issue 100 are related to this.
+Surveys, or at least the techniques used to achieve them, could be used more widely to make existing Models extensible. Issue 520 (on Google Code) and Issue 100 (on Google Code) are related to this.
A past GSOC survey is viewable here: https://spreadsheets.google.com/viewform?formkey=cjV0aVVtcGhtdEdhSnp5bTl6b2Fob1E6MA
-= Evaluation Walkthrough =
+# Evaluation Walkthrough
Creating a survey is a simple 3-step process.
-The first step is to configure the administrative attributes of the survey, such as its name and read/write access privileges. These attributes are comparable to those for documents and other Melange entities.
+The first step is to configure the administrative attributes of the survey, such as its name and read/write access privileges. These attributes are comparable to those for documents and other Melange entities.
The second step is to determine who the survey is for. A survey can be open to anyone, or it can also be used for a midterm/final evaluation. If the survey is being used for an evaluation, two surveys should be made - one for students, and one for mentors. (The student projects shared by these students and mentors is used to link pairs of mentor/student surveys so they can be retrieved together)
-The third step is to create the survey content itself. This should be an intuitive process. Note that you can set custom prompts for questions and re-order options for select fields and checkbox fields.
+The third step is to create the survey content itself. This should be an intuitive process. Note that you can set custom prompts for questions and re-order options for select fields and checkbox fields.
-(this walkthrough will be expanded when midterm features for GSOC2009 are finalized)
+(this walkthrough will be expanded when midterm features for GSOC2009 are finalized)
-= Models =
+# Models
There are three model classes used for surveys - Survey, SurveyContent, and SurveyRecord.
-The Survey model describes read/write permissions and metadata of the survey entity, such as whether it is featured, and who has created and edited it.
+The Survey model describes read/write permissions and metadata of the survey entity, such as whether it is featured, and who has created and edited it.
The SurveyContent model is a db.Expando() class where each property is the name of a field of the survey, and the value of the property contains information such as the prompt for the question and choices for a selection field. A schema property included in each instance is a dictionary describing what type of question each field is, such as selection (choice), short answer, or long answer.
The SurveyRecord model is also a db.Expando() class, and each property is the name of a field for the given survey and the value is the supplied answer. The SurveyRecord refers to the user who took the survey and the Survey entity in question.
-Working with db.Expando() classes is mostly very straightforward. Python's getattr() and setattr() method are used to access survey fields since we don't know the name of the property/field in advance.
+Working with db.Expando() classes is mostly very straightforward. Python's getattr() and setattr() method are used to access survey fields since we don't know the name of the property/field in advance.
-= Views =
+# Views
The Survey view and logic mostly inherited from the base classes, with some modifications since the properties saved and retrieved are dynamic in nature.
There are also classes in views/helper/surveys.py to render widgets used to create, edit, and take surveys, and list survey results.
-The survey listing functionality is significantly modified from the base List class, also because the properties used to generate the list form are not hard-coded into the model class.
+The survey listing functionality is significantly modified from the base List class, also because the properties used to generate the list form are not hard-coded into the model class.
-= Front-End =
+# Front-End
-The take_survey.js and edit_survey.js modules facilitate the creation and taking of surveys on the front-end. It is mostly straightforward jQuery DOM manipulation.
+The take\_survey.js and edit\_survey.js modules facilitate the creation and taking of surveys on the front-end. It is mostly straightforward jQuery DOM manipulation.
-= Grading =
+# Grading
A requirement for the midterm administration of surveys will be that survey results can be graded using a binary distinction like pass/fail. Since this feature won't be universal to surveys, the SurveyRecord class has been subclassed as MidtermRecord, with an additional 'project' and 'grade' property.
-Assuming that mentors aren't graded as students are, the grading feature should be conditional on a student taking the test, and to access the test, the student must have a project associated with the program associated with the survey.
+Assuming that mentors aren't graded as students are, the grading feature should be conditional on a student taking the test, and to access the test, the student must have a project associated with the program associated with the survey.
-The scope_path property of the survey can be used to get the program associated with the survey, and verify that the survey-taker has permission to take the survey. The Survey model inherits from the soc.models.work.Work class, so it uses the Linkable class to give it a scope_path containing the program id.
+The scope\_path property of the survey can be used to get the program associated with the survey, and verify that the survey-taker has permission to take the survey. The Survey model inherits from the soc.models.work.Work class, so it uses the Linkable class to give it a scope\_path containing the program id.
On the front-end, the grading feature for the survey edit view can be added by editing the row template for the results list so that each row includes a widget beside it consisting of two buttons to toggle pass/fail for the survey result on that row. A "save survey grades" button is added at the bottom.
@@ -93,13 +91,12 @@
-== TODO ==
+## TODO
-- (James) A view for org_admins to see completed records and uncompleted surveys for projects.
+- (James) A view for org\_admins to see completed records and uncompleted surveys for projects.
- Better handling of cases where POST is not successfully sent. (Confirmation e-mail, etc.)
-- Send notifications to users who have not yet taken surveys. This would most likely be in the form of a button on the create/edit page.
+- Send notifications to users who have not yet taken surveys. This would most likely be in the form of a button on the create/edit page.
-- Test Suite, Integration with seed_db, etc.
-
\ No newline at end of file
+- Test Suite, Integration with seed\_db, etc.
