SurveysModule.wiki

#summary Design/discussion for Surveys
#labels Importance-Useful,Phase-Requirements,Contents-Draft

<wiki:toc max_depth="3" />

= GSoC Project Info =

|| James Levy || [http://socghop.appspot.com/student_project/show/google/gsoc2009/melange/t124022698643 Project description] ||

= 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. 

Each year the questions asked change slightly.

The intent of surveys is that the program admin can set up the questions and collect the answers.

  * Planned Surveys
    * Mid term progress (by student)
    * Mid term progress (by mentor - determines whether student gets mid-term payment)
    * Final survey (by student)
    * Final survey (by mentor - determines whether student passes overall)
    * Final survey (by admin(s)) - Feedback on orgs participation
  * 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.

A past GSOC survey is viewable here: https://spreadsheets.google.com/viewform?formkey=cjV0aVVtcGhtdEdhSnp5bTl6b2Fob1E6MA



= 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 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. 

(this walkthrough will be expanded when midterm features for GSOC2009 are finalized) 



= 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 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. 


= 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. 


= 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. 


= 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. 

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.

On submission, a serialized array is sent in the POST that has pass/fail/none as options that are saved as a 'grade' property for the particular SurveyResult entity. The id of the survey result can be used as an identifier for this process.

The grade property of the SurveyResult can then be retrieved for any other view, given a project entity or a program entity.



== TODO == 

- (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. 

- Test Suite, Integration with seed_db, etc.