Differences
This shows you the differences between two versions of the page.
— |
foundation:surveytool_spec [2010/12/18 17:35] (current) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | Functional Specifications for the [[http:// | ||
+ | \\ \\ | ||
+ | ^Revision History^^^^ | ||
+ | ^Version^Author^Date^Comments^ | ||
+ | |0.1|Robby O' | ||
+ | |0.2|Michael Howden|2010-05-22|First Review.| | ||
+ | |0.3|Robby O' | ||
+ | |0.4|Robby O' | ||
+ | |0.5|Robby O' | ||
+ | |0.6|Robby O' | ||
+ | |0.7|Robby O' | ||
+ | |0.8|Robby O' | ||
+ | |0.9|Robby O' | ||
+ | |1.0|Robby O' | ||
+ | |1.1|Robby O' | ||
+ | |1.2|Robby O' | ||
+ | \\ | ||
+ | |||
+ | |||
+ | ====== Overview ====== | ||
+ | In the aftermath of a natural disaster, it is imperative that the extent of the damages be evaluated in a timely manner. Enter stage right, Survey Tool: A tool to create, manage, and enter surveys to assess the needs of the peoples affected by the natural disaster to deliver the much needed aid in an efficient manner. | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ====== Background Scenarios and User Stories ====== | ||
+ | Lucy has to conduct a survey on 100,000 people living in a conflict affected part of Africa. She wants to be able generate this survey, and then have it filled in by hand. These paper survey will then be collated by a number of data entry operators. [seperate instances in a series with 100,000 instances] | ||
+ | |||
+ | Karl has to conducting a survey of schools in Iraq. This survey will be carried out initially, to collect baseline data (to better design an assistance program), and then repeated to track the performance of the program over it's duration. | ||
+ | |||
+ | Tom, Dick and Harry work for different organisations all in Haiti responding to the earthquake. Each of their organisations have a different assessment for, but they would like to be able to share informations, | ||
+ | |||
+ | Different surveys will be aggregated differently. | ||
+ | In Lucy's case, we will be looking at averages over the entire population | ||
+ | In Tom Dick and Harry' | ||
+ | |||
+ | An instance of a survey template may only contain one answer eg, an assessment of a village. | ||
+ | Or it might contain 100,000 | ||
+ | \\ \\ | ||
+ | ====== Non-Goals ====== | ||
+ | (to be completed) | ||
+ | \\ \\ | ||
+ | ====== Definitions ====== | ||
+ | **Super Users** - have access to do EVERYTHING | ||
+ | |||
+ | |||
+ | **Data Entry Clerks** - People who enter the data. | ||
+ | \\ \\ | ||
+ | ====== Users ====== | ||
+ | * People setting up surveys -> super users | ||
+ | * people filling out surveys -> data entry clerks, super users | ||
+ | * viewing results -> data entry clerks, super users | ||
+ | \\ \\ | ||
+ | ====== Data Model ====== | ||
+ | |||
+ | ** Survey Template**\\ | ||
+ | Holds information on a survey template. Question, | ||
+ | |||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |name|Acts as the display name -- the title of the survey|string|Yes| | ||
+ | |description|Description of this template|text|No|| | ||
+ | |locked|Prevent modifying a survey which is being edited|boolean|No| | ||
+ | |author|Who created this template|FK to pr_person.id|No -- defaults to logged in user| | ||
+ | |organisation|The organisation that this template is used for|FK to org_organisation.id|Yes|| | ||
+ | |||
+ | \\ | ||
+ | ** Survey Question**\\ | ||
+ | Holds information about Survey Questions. | ||
+ | |||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |name|acts as the display name for the question|string|Yes| | ||
+ | |description|Description of this question|text|No| | ||
+ | |question_type|denotes the question type (see section on question types).|FK to survey_question_type|Yes| | ||
+ | |||
+ | \\ | ||
+ | ** Survey Section **\\ | ||
+ | Holds information about survey sections. | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |name|acts as the display name for the section|string|Yes| | ||
+ | |description|Description of this section|text|No| | ||
+ | |||
+ | \\ | ||
+ | ** Survey Series**\\ | ||
+ | Associate a survey (or set of surveys with a series) | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |name|the name of the series|string|Yes| | ||
+ | |description|Description of the series|text|No| | ||
+ | |survey_template_id|Associated Survey Template|FK to survey_template.id|Yes|| | ||
+ | |from_date|Start of period|datetime|Yes|| | ||
+ | |to_date|End of period|datetime|Yes| | ||
+ | |location|Location Survey Conducted.|FK to gis_location.id|Yes| | ||
+ | |||
+ | \\ | ||
+ | ** Survey Instance**\\ | ||
+ | Holds the records for each survey answered in a survey series | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |survey_series_id|The series to which this instance refers to|FK to survey_series.id|Yes| | ||
+ | \\ | ||
+ | ** Survey Answer **\\ | ||
+ | Holds answers to surveys to be displayed if survey is answered. | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |survey_instance_id|The instance this answers refers to|FK to survey_instance.id|Yes|| | ||
+ | |question_id|Question to which this being answered for|FK reference to the survey_question.id|Yes| | ||
+ | |answer_value|the answer|string|Yes| | ||
+ | |comments|the comments (if any)|text|No| | ||
+ | |||
+ | \\ | ||
+ | ** Survey Template Link Table **\\ | ||
+ | Link table to solve the many-to-many relation between: Surveys< | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |question_id|Survey Question|FK to survey_question.id|No| | ||
+ | |section_id|Survey Section|FK to survey_section.id|No| | ||
+ | |survey_template_id|Survey Template|FK to survey_template.id|No| | ||
+ | |order|The order which the question appears in the survey|int|No| | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ** Question Metadata **\\ | ||
+ | Used to store configuration data | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |question_id|Question these options are related to.|FK to survey_question.id|Yes| | ||
+ | |row_choice|row choice for rating|text|No| | ||
+ | |column choice|column choice for rating (can customize)|text|No| | ||
+ | |ta_rows|how many rows for the text-area|int|No| | ||
+ | |tf_ta_columns|The number of rows for either Text Field or Text Area|int|No| | ||
+ | |allow_comments|Whether or not to render a comment field|boolean|No| | ||
+ | |comment_display_label|The comment to text display before the text field for comments|string|No| | ||
+ | |required|Whether or not the question should be required to be filled out|boolean|No| | ||
+ | |validate|Whether or not to enable validation for the question|boolean|No|| | ||
+ | |aggregation_type|How the question should be aggregated (non-editable by the user|string|No|\\ \\ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ** Survey Widgets (Custom Data Types) **\\ | ||
+ | Used to store configuration data | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |question_id|Question this widget is related to.|FK to survey_question.id|Yes|| | ||
+ | |widget|The render-able markup used to render the question|text|Yes|\\ \\ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ** Survey Answer Options** \\ | ||
+ | Used to store the answer options (e.g., Yes, No, Not Applicable) | ||
+ | ^Field Name^Purpose^Data type^Required^ | ||
+ | |question_id|Question these answer options are related to.|FK to survey_question.id|Yes|| | ||
+ | |option_value|The value to display e.g., " | ||
+ | |||
+ | \\ \\ | ||
+ | |||
+ | |||
+ | ====== Question Data Types====== | ||
+ | |||
+ | Internally question types are stored *NUMERICALLY*. | ||
+ | |||
+ | - Multiple Choice (Only One Answer): {{: | ||
+ | - Multiple Choice (Multiple Answers): {{: | ||
+ | - Rating Scale: {{: | ||
+ | - Single Textbox | ||
+ | - Multiple Textboxes | ||
+ | - Comment/ | ||
+ | - Large text-area to take in an essay or comment. | ||
+ | - Numerical textboxes | ||
+ | - This has validation that ensures that a numeric answer is given. | ||
+ | - Date and/or Time | ||
+ | - Datepicker will be used here. | ||
+ | - Image | ||
+ | - Simple way of having a logo or branding on the survey. | ||
+ | - Descriptive Text | ||
+ | - A way to have some prose in whatever form necessary | ||
+ | - Location | ||
+ | - Organisation | ||
+ | - Person | ||
+ | - Custom Database Resource (any resource defined in eden is possible here). | ||
+ | \\ \\ | ||
+ | ====== Flowcharts====== | ||
+ | |||
+ | {{{: | ||
+ | |||
+ | \\ \\ | ||
+ | ====== Screens ====== | ||
+ | {{: | ||
+ | Now the add question form\\ | ||
+ | {{: | ||
+ | \\ | ||
+ | |||
+ | The pop-up generated when "Add Question is clicked will be a wizard-style ui with two steps as shown in the following (**NB: this is only for ONE data type and there are other variants of the configuration page, this gives an idea of what it will look like.)**:\\ | ||
+ | {{: | ||
+ | |||
+ | \\ | ||
+ | |||
+ | The pop-up generated when "Add Section" | ||
+ | {{: | ||
+ | |||
+ | \\ | ||
+ | |||
+ | **The home screen looks like follows: | ||
+ | {{: | ||
+ | \\ | ||
+ | **Finally, the analysis page will look like this:**\\ | ||
+ | {{: | ||
+ | \\ \\ | ||
+ | |||
+ | ====== Wizard Steps===== | ||
+ | |||
+ | ^Survey Creation^^ | ||
+ | ^Step Number^Page^ | ||
+ | |1|Survey Template| | ||
+ | |2|Add Questions/ | ||
+ | |3|Add Series/ | ||
+ | \\ \\ | ||
+ | **Questions have a sort of " | ||
+ | ^Question Creation^^ | ||
+ | ^Step Number^Page^ | ||
+ | |1|Survey Question| | ||
+ | |2|Survey Question Options Configuration| | ||
+ | |||
+ | ====== UI Design ====== | ||
+ | -> implies going to a new screen | ||
+ | |||
+ | **Menu**: | ||
+ | |||
+ | * Create | ||
+ | * Fill Out | ||
+ | * Results | ||
+ | * Analysis | ||
+ | * Advanced | ||
+ | |||
+ | |||
+ | **Screens**: | ||
+ | |||
+ | **__Home__**: | ||
+ | |||
+ | * Big Button for create | ||
+ | * List of recently created surveys | ||
+ | * List of recently added surveys to fill out | ||
+ | * List of recently completed surveys | ||
+ | |||
+ | |||
+ | **__Create__**: | ||
+ | |||
+ | * Option to re-use an existing survey -> who take you straight to " | ||
+ | * Option to edit an existing survey -> who take you straight to " | ||
+ | * Option to retake a completed survey using a different survey template, which has overlap with the past survey, but also contains new questions. The overlapping questions could be prefilled with the results from the previous survey. | ||
+ | * Option to go through the survey create wizard: | ||
+ | |||
+ | - Enter Survey Name, other details | ||
+ | - Enter survey sections. | ||
+ | - Add questions. This will be One of the major pages: | ||
+ | |||
+ | |||
+ | * Create Survey -> Who, When, where, Why. The same " | ||
+ | |||
+ | **__Fill Out__**: | ||
+ | |||
+ | * List of all surveys which can be filled out -> Data entry screen for that survey / Print out survey question sheet | ||
+ | |||
+ | |||
+ | **__Results__**: | ||
+ | |||
+ | * List of all surveys there are results for (Which the user has permission to view) option to " | ||
+ | |||
+ | |||
+ | **__Analysis__**: | ||
+ | |||
+ | * List of Surveys (grouped so that instances of the same survey are together) -> analysis page for that survey. Allow user to add notes to the results for each question | ||
+ | * Export the data to excel | ||
+ | * We will need to be able to analyse different surveys together: eg NGO A did survey A, NGO B did survey B, OR NGO A did survey A in Jan 2010 then NGO A did survey A in Dec 2010 | ||
+ | |||
+ | - compare the actual surveys (not the questions) - how similar are they? | ||
+ | - Add the answers together | ||
+ | - what is the difference between the results (eg change from Jan-Dec) | ||
+ | \\ \\ | ||
+ | ====== API ====== | ||
+ | |||
+ | (to be completed later) | ||
+ | \\ \\ | ||
+ | ====== Technologies ====== | ||
+ | (to be completed later) | ||
+ | \\ \\ | ||
+ | ======References====== | ||
+ | [[http:// | ||
+ | \\ \\ | ||
+ | ======Open Issues====== | ||
+ | **None to date.** | ||
+ | \\ \\ | ||
+ | ======Comments====== | ||
+ | **None** | ||
+ | \\ \\ | ||
+ | ======Nice to have====== | ||
+ | |||
+ | * Ability to " | ||
+ | * PDF export | ||
+ | * Localization of sections and questions (see section following this one for two approaches) | ||
+ | |||
+ | ======Localization====== | ||
+ | One approach (Robby O' | ||
+ | |||
+ | Two tables (section_localization, | ||
+ | |||
+ | - section_id (FK to survey_section.id) and question_id (FK to survey_question.id) respectively. | ||
+ | - locale (i18n locale, e.g., en_UK, en_AU, en_US, | ||
+ | - name (localized name) | ||
+ | - description (localized description) | ||
+ | |||
+ | |||
+ | Alternative approach, the appeal to this approach is as opposed to splitting sections and question localization into two tables, we combine them into one. Either approach is sound: | ||
+ | |||
+ | One table, survey_localization and the following fields: | ||
+ | |||
+ | - section_id (FK to survey_section.id) | ||
+ | - question_id (FK to survey_question.id) | ||
+ | - locale (i18n locale, e.g., en_UK, en_AU, en_US, | ||
+ | - name (localized name) | ||
+ | - description (localized description) | ||