Requirement specification document for the TIMCAN-project

Hanna Alatalo
Jarkko Kuivanen
Elisa Nauha
Jere Ojala
Kimmo Urtamo
Version 0.0.5
Private
2.4.2019
University of Jyväskylä
Faculty of Information Technology
Jyväskylä

Acceptor	Date	Signature	Name clarification
Project Lead			Elisa Nauha
Customer representative			Ari Huhta
Customer representative			Dmitri Leontjev
Supervisor			Jukka-Pekka Santanen

1. Introduction

!

The TIMCAN-project is further developing the TIM-system developed in the Faculty of Information Technology in the University of Jyväskylä. The goal of this project group's development is to make the system more suitable for the Centre of Applied Language Studies. Currently they are using an application called ICAnDoiT that is no longer being developed or supported. This project will develop the functions from the ICAnDoiT-application into the TIM-system.

The most important function of the ICAnDoiT-application is giving dynamic feedback where the feedback received by the student depends on their previous answers. It is also necessary to develop new exercise types to the TIM-system. A way to get the path of the student's answers as a report is important for research. One of the goals of the project is also making the functions above available to other users of the TIM-system.

The format of this document is based on Titus-project's requirement specification document^[1] (in Finnish). The beginning of this document establishes the concepts used later on. After that a description of the system being developed, target for it's development and the system's current application and user groups are given. The document describes the system's expanded domain and new user groups as well as how the previous ICAnDoiT-application operates and how it is being transferred to the TIM-system. The essential content of the requirement specification are the requirements of the functions being developed as well as their priorities and states. Requirements specification is used for managing and tracking the requirements during the course of the project.

This document doesn't go into details about the challenges, goals or needs of the project. Instead those are covered in the TIMCAN-project's project plan^[2] (in Finnish). Other notable documents are the project report^[3] (in Finnish) and the application report ^[4]. There is also a manual^[5] available and instructions^[6] for further development.

2. Concepts

!

This chapter presents the essential concepts used in this document.

2.1 Concepts related to the domain

!

This document uses the domain-specific concepts described below:

• TIM is an interactive study environment developed in the University of Jyväskylä.
• ICAnDoiT is an application developed by and currently used in the Centre of Applied Language Studies to do research on dynamic feedback.
• Dynamic feedback is feedback that changes depending on the answer given and feedback level.
• Feedback level tells, how specific feedback the performing party receives based on their answers. Feedback level increases with incorrect answers and optionally decreases with correct answers.
• Test is a collection of tasks.
• Task is a collection of similar question items with dynamic feedback included.
• Question item is a single question.

2.2 Concepts related to requirement specification

!

This document uses the following concepts in connection to (concerning?) requirement specification:

• Stakeholders comprise of people and organizations utilizing the software being developed.
• Domain includes those making use of the work put towards the development such as the field of business, application, duties and stakeholders.
• General goal is a goal set to improve upon the content or quality of operations in the organization.
• User is the end-user of the software.
• User role or role is a usertype that has certain responsibilities, rights or tasks in relation to the system being used.
• Usergroup is a group of users defined in the information system that can also include roles.
• Need is the data and functions as a whole needed by the stakeholders or organization, improving the content or quality of stakeholder operations in relation with the actions supported by the system being developed.
• Goal is a whole derived from general goals and stakeholder needs and problems which, when reached, improve the stakeholder operations.
• Wish is a preliminary objective related to results or development of a function, presented by someone from the stakeholders.
• Requirement is a specific description of a single function or a piece of data derived from domain goals.
• Requirement specification is a document presenting single requirements, goals and needs in connection to the project as well as all written or illustrated material related to it.

2.3 Technical concepts

!

This document uses the following concepts in connection to programming and programming tools:

• CSS (Cascading Style Sheets) is a style description file used in web-documents to modify their appearance.
• CSV (Comma-separated values) is a text file format where values are separated with commas for easy and universal interpretation.
• Docker is an application to run other applications in virtual containers.
• Git is an open-source version control system for source code.
• GitLab is a web browser-based Git-application used in this project for version control.
• HTML is a markup language for creating web pages and describing their structure. The pages consists of HTML elements.
• Id is an identifier to separate individuals.
• JavaScript is a coding language that is used to add interactivity to web pages.
• JSON (JavaScript Object Notation) is a simple file format for data transfer. It is regularly used in web-based systems.
• Paragraph-editor is a text editor used in TIM to modify a single paragraph.
• Markdown is a marking language that is used in TIM-documents.
• Plugin is a part of TIM-system that adds functionality to documents.
• YAML (YAML Ain't Markup Language) is a markup-language.

3. TIM

!

This chapter describes the system that the functionality in the project is being developed for.

3.1 TIM-system

!

3.2 User groups and user rights

!

For the tests it is essential that different user rights are easy to manage.

The following user groups need to be considered in rights management:

• the researcher or teacher that creates the test,
• the test subject that takes the test and
• the student that takes the test.

The creators of the tests need to have rights to create and modify documents that will act as tests as well as modify their publicity. Unfinished tests cannot be available to anyone other than their creator. The creator will make the tests visible to test takers after they are finished.

4. Centre of Applied Language Studies and ICAnDoiT

!

This chapter describes the previous application and the department it is being used in.

The Centre of Applied Language Studies or CALS specializes in studying the goals, practices and policies of language education. In their research they focus on language testing, the development of language proficiency in different contexts and communities of practice, and language education policy.

5. Priorities and states of the requirements

!

In this document the requirements are divided based on the functions that need to be developed. The following priorities are used in the requirements:

• Essential requirement is necessary for the application to function.
• Important requirement gives value to the user but is not required for the application to function.
• Possible requirement can be implemented another way or the value is minimal compared to resource cost.
• Idea the requirement needs are not clear yet or the need for the requirement is so small that the implementation depends on leftover resources.
• Discarded requirement has been deemed unnecessary.

This document also tracks the realization of requirements by using states. The following states are used:

• In TIM the requirement has already been completed in the system.
• Approved requirement has been completed, tested and approved.
• Tested requirement has been completed and tested but not approved.
• Completed requirement has been completed but not tested.
• Unfinished requirement is under development.
• Not Started development on the requirement hasn't begun yet.
• Not Implemented agreement has been made with the customer to not implement the requirement in the TIMCAN-project.

6. User stories

Seuraavassa esitellään sovelluksen käytöstä kirjoitettuja käyttäjätarinoita jaettuna testin luomiseen, testiin vastaamiseen sekä testin raportin pyytämiseen.

6.1 Creating a test

• !Laatija määrittelee ohjeet, jotka esitetään tehtävään vastaajalle.
• Laatija luo mallitehtävän ja siihen liittyvät palautteet.
• Laatija luo tehtävät ja liittää niihin mallitehtävään liittyvät palautteet.
• !Laatija luo harjoitustehtävän, josta vastaaja ei saa palautetta.
• !Laatija pystyy lainaamaan palautteessa vastaajan valitsemaa vastausvaihtoehtoa.
• !Laatija pystyy lainaamaan palautteessa tehtävän oikeaa vastausta.
• !Laatija pystyy luomaan tehtävän graafisen käyttöliittymän avulla käyttäen pohjia: drag&drop, dropdown ja feedback.
• !Laatija pystyy luomaan tehtävän tekstieditoria käyttäen.
• !Laatija pystyy valitsemaan ohjeelle valmiin pohjan graafisesta käyttöliittymästä.
• !Laatija pystyy valitsemaan palautteelle valmiin pohjan graafisesta käyttöliittymästä.
• !Laatija voi luoda tehtäväsarjan, joka sisältää sen ohjeet, mallitehtävän, palautteet ja tehtäviä.
• !Laatija voi luoda testin, joka sisältää tehtäväsarjoja.
• !Laatija voi asettaa lopetusehdon, jolla testin suoritus päättyy:
  • !Tehtäväsarja voidaan asettaa loppumaan, jos viimeinen palautetaso saavutetaan.
  • !Tehtäväsarja voidaan asettaa loppumaan, jos tehtävän tekijä saa putkeen X määrän kysymyksiä oikein.
  • !Tehtäväsarja voidaan asettaa loppumaan, jos tehtävän tekijä saa putkeen X määrän kysymyksiä väärin.

6.2 Question item types

6.2.1 Dropdown

• !Alasvetovalikossa täytyy valita jokin muu kuin tyhjä oletussarake ja
• !raahaustehtävissä täytyy kaikkissa pudotuspaikoissa olla raahattuna sana.

6.2.2 Drag&drop

6.3 Dynamic feedback

• !Vastaaja siirtyy palautetasossa alaspäin väärästä vastauksesta.
• !Vastaaja saa tarkentuvaa palautetta väärien vastausten perusteella.
• !Laatija voi asettaa vastaajan nousemaan palautetasossa oikeasta vastauksesta.
• !Laatija voi asettaa vastaajan pysymään samalla palautetasolla oikeasta vastauksesta.

6.4 Exporting reports

• !Testin laatija voi pyytää vastauksista raportin.
• !Vastaajan vastatessa tallentuu raportin vaatimat tiedot.
• !Tutkija pystyy hakemaan testin vastauksista raportin csv-muodossa.
• !Raportti sisältää: koehenkilön yksilöintitiedot, kysymykset, vastaukset, palautteet, tehtävien tekoon käytetyn ajan ja palautteen lukemiseen käytetyn ajan.
• !Tutkija näkee raportista vastaajan kulkeman vastauspolun
• !Tutkija näkee raportista vastaajan kulkeman palautepolun.
• !Opettajan pyytämä raportti sisältää: koehenkilön yksilöintitiedot, kysymykset, vastaukset ja pisteet.

6.5 Test presentation

• !Tehtäviin vastaaja lukee ohjeet ennen tehtäväsarjan aloittamista.
• !Vastaaja kuittaa ohjeet luetuksi.
• !Vastaaja valitsee vastauksen ja kuittaa sen.
• !Vastaaja saa palautteen jokaisen vastatun tehtävän jälkeen.
• !Vastaaja siirtyy seuraavaan tehtävään kuitattuaan palautteen.
• !Vastaajalle esitetään harjoituskysymys ohjeiden lukemisen jälkeen.
• !Vastaaja näkee vastauksensa osana palautetta.
• !Vastaaja näkee vain yhden seuraavista kerrallaan: ohje, tehtävä tai palaute.
• !Vastaaja ei saa harjoituskysymykseen vastatessaan palautetta.
• !Vastaaja voi lopettaa tehtävän suorituksen ja jatkaa myöhemmin siitä, mihin jäi.
• !Vastaaja voi siirtyä tehtävästä eteenpäin antamatta tehtävätyypille sopivaa vastausta
• !Vastaaja ei näe testiin liittymättömiä käyttöliittymäelementtejä.
• !Vastaajan vastattua testin viimeiseen tehtävään sovellus ilmoittaa testin päättymisestä.
• !Vastaajan täytettyä lopetusehdon tehtäväsarja päättyy ja seuraava tehtäväsarja alkaa.
• !Vastaajan täytettyä kaikkien tehtäväsarjojen lopetusehdot testi päättyy.
• !Vastaaja ei pääse tarkastelemaan edellisiä ohjeita, tehtäviä tai palautteita.
• !Vastaaja pääsee tarkastelemaan edellisiä ohjeita, tehtäviä tai palautteita.

6.6 Non-functional

7. Requirements for creating a test

!

No.	Description	Priority	Notes	State
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-

8. Requirements for the question item types

!

This chapter describes the requirements for the two question item types that the TIMCAN-project will develop. These are:

• an ordering-type question item where words are dragged from a pool to form sentences and
• a question item where you select the correct answer from a dropdown-menu of multiple choices.

8.1 Common requirements for question items

!

No.	Description	Priority	Notes	State
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-

8.2 Requirements for ordering-type question items

!

No.	Description	Priority	Notes	State
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-

8.3 Requirements for multiple choice question items

!

No.	Description	Priority	Notes	State
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-
1.1	abc	low	-	-

9. Requirements for the dynamic feedback

!

No.	Description	Priority	Notes	State
1.1	The dynamic feedback shall be divided into levels.	high	-	-
1.2	The dynamic feedback shall become more detailed on wrong answers.	high	-	-
1.3	The dynamic feedback level shall go down on wrong answers.	high	-	-
1.4	The dynamic feedback level may go up on right answers	low	-	-
1.5	The low - -
1.6	abc low - -

10. Requirements for exporting reports

!

No.	Description	Priority	Notes	State
1.1	The report shall include the subject's identifier.	high	-	-
1.2	The report shall include the tasks completed.	high	-	-
1.3	The report shall include the subject's answers.	high	-	-
1.4	The report shall include the feedback the subject received.	high	-	-
1.5	The report shall include the time used to answer individual question items.	high	-	-
1.6	The report shall include the time used to read feedback.	high	-	-
1.7	The report shall include the points received by the subject.	low	-	-
1.8	The report shall be exportable in CSV.	high	-	-
1.9	The report shall . low - -
1.10	The report shall. low - -

11. Requirements for test presentation

!

No.	Description	Priority	Notes	State
1.1	The subject shall be presented instructions before performing the test.	high	-	-
1.2	The subject shall be presented a sample item for a new question item type.	high	-	-
1.3	The subject shall only see instructions, a question item or feedback.	high	-	-
1.4	The subject shall receive feedback after answering a question item.	high	-	-
1.5	The subject shall see their answer as part of feedback.	low	-	-
1.6	The subject shall not see UI-components unrelated to the test.	low	-	-
1.7	The test shall end when there are no more question items to present.	low	-	-
1.8	The subject cannot move to the next question without selecting an answer.	low	-	-
1.9	The. low - -
1.10	The . low - -

12. Non-functional requirements

!

• Easy to use for people with regular computer knowledge.
• Making of new question item types.
• The quality of source code for further development.

13. Fulfilment of requirements

!

This chapter describes the functionality developed in the TIMCAN-project and the number and fulfilment of functional requirements as a whole as well as ordered by the function.

13.1 Fulfilment of requirements as a whole

State/Priority	Essential	Important	Possible	Idea	Discarded	Total
In TIM	0	0	0	0	0	0
Approved	0	0	0	0	0	0
Tested	0	0	0	0	0	0
Completed	0	0	0	0	0	0
Unfinished	0	0	0	0	0	0
Not Started	0	0	0	0	0	0
Not Implemented	0	0	0	0	0	0
Total	0	0	0	0	0	0

13.2 Fulfilment of requirements for creating a test

State/Priority	Essential	Important	Possible	Idea	Discarded	Total
In TIM	0	0	0	0	0	0
Approved	0	0	0	0	0	0
Tested	0	0	0	0	0	0
Completed	0	0	0	0	0	0
Unfinished	0	0	0	0	0	0
Not Started	0	0	0	0	0	0
Not Implemented	0	0	0	0	0	0
Total	0	0	0	0	0	0

13.3 Fulfilment of requirements for ordering-type question items

State/Priority	Essential	Important	Possible	Idea	Discarded	Total
In TIM	0	0	0	0	0	0
Approved	0	0	0	0	0	0
Tested	0	0	0	0	0	0
Completed	0	0	0	0	0	0
Unfinished	0	0	0	0	0	0
Not Started	0	0	0	0	0	0
Not Implemented	0	0	0	0	0	0
Total	0	0	0	0	0	0

### Fulfilment of requirements for multiple choice-question items {id="0tVP8DNGk1oi"}

---------------------------------------------------
State/Priority   Essential      Important    Possible    Idea    Discarded    Total
--------------   ---------      ---------    --------    ----    ---------    ------
In TIM              0               0           0          0        0           **0**

Approved            0               0           0          0        0           **0**

Tested              0               0           0          0        0           **0**

Completed           0               0           0           0       0           **0**

Unfinished          0               0           0           0       0           **0**

Not Started         0               0           0           0       0           **0**

Not Implemented     0               0            0           0      0           **0**

**Total**           **0**         **0**         **0**       **0**   **0**       **0**
---------------------------------------------------

### Fulfilment of requirements for the dynamic feedback {id="tA8eO4GIYLK5"}

---------------------------------------------------
State/Priority   Essential      Important    Possible    Idea    Discarded    Total
--------------   ---------      ---------    --------    ----    ---------    ------
In TIM              0               0           0          0        0           **0**

Approved            0               0           0          0        0           **0**

Tested              0               0           0          0        0           **0**

Completed           0               0           0           0       0           **0**

Unfinished          0               0           0           0       0           **0**

Not Started         0               0           0           0       0           **0**

Not Implemented     0               0            0           0      0           **0**

**Total**           **0**         **0**         **0**       **0**   **0**       **0**
---------------------------------------------------

### Fulfilment of requirements for exporting reports {id="FaTc8C3y1xoH"}

---------------------------------------------------
State/Priority   Essential      Important    Possible    Idea    Discarded    Total
--------------   ---------      ---------    --------    ----    ---------    ------
In TIM              0               0           0          0        0           **0**

Approved            0               0           0          0        0           **0**

Tested              0               0           0          0        0           **0**

Completed           0               0           0           0       0           **0**

Unfinished          0               0           0           0       0           **0**

Not Started         0               0           0           0       0           **0**

Not Implemented     0               0            0           0      0           **0**

**Total**           **0**         **0**         **0**       **0**   **0**       **0**
---------------------------------------------------

### Fulfilment of requirements for test presentation {id="NZ8n6z3cACnf"}

---------------------------------------------------
State/Priority   Essential      Important    Possible    Idea    Discarded    Total
--------------   ---------      ---------    --------    ----    ---------    ------
In TIM              0               0           0          0        0           **0**

Approved            0               0           0          0        0           **0**

Tested              0               0           0          0        0           **0**

Completed           0               0           0           0       0           **0**

Unfinished          0               0           0           0       0           **0**

Not Started         0               0           0           0       0           **0**

Not Implemented     0               0            0           0      0           **0**

**Total**           **0**         **0**         **0**       **0**   **0**       **0**
---------------------------------------------------

#- {id="FBW2ZL3IKNzf"}

#- {id="Lbry2Lo94rxw"}

## Summary {id="6wRkwUjjWorh"}
[!]{.red}

#- {id="Xme39hLW87XX"}

## References {id="y0x7fOsnFpgV" .nonumber}
[!]{.red}\
[1] Matti Leinonen, Ronja Lindholm, Visa Naukkarinen, Rami Pasanen and Enni Stylman.\
Titus-projektin vaatimusmäärittely\
[`https://tim.jyu.fi/view/kurssit/tie/proj/2018/titus/dokumentit/vaatimusmaarittely`](https://tim.jyu.fi/view/kurssit/tie/proj/2018/titus/dokumentit/vaatimusmaarittely)
University of Jyväskylä, Faculty of Information Technology. 2018.

[2] Hanna Alatalo, Jarkko Kuivanen, Elisa Nauha, Jere Ojanen and Kimmo Urtamo.\
TIMCAN-projektin projektisuunnitelma.\
[`https://tim.jyu.fi/view/kurssit/tie/proj/2019/timcan/dokumentit/projektisuunnitelma_timcan`](https://tim.jyu.fi/view/kurssit/tie/proj/2019/timcan/dokumentit/projektisuunnitelma_timcan)\
University of Jyväskylä, Faculty of Information Technology. 2019.

[3] Hanna Alatalo, Jarkko Kuivanen, Elisa Nauha, Jere Ojanen and Kimmo Urtamo.\
Report of the TIMCAN-project.\
[asdf](asdf)\
University of Jyväskylä, Faculty of Information Technology. 2019.

[4] Hanna Alatalo, Jarkko Kuivanen, Elisa Nauha, Jere Ojanen and Kimmo Urtamo.\
Report of the application developed in TIMCAN-project.\
[asdf](asdf)\
University of Jyväskylä, Faculty of Information Technology. 2019.

[5] Hanna Alatalo, Jarkko Kuivanen, Elisa Nauha, Jere Ojanen and Kimmo Urtamo.\
Manual of the application developed in TIMCAN-project.\
[asdf](asdf)\
University of Jyväskylä, Faculty of Information Technology. 2019.

[6] Hanna Alatalo, Jarkko Kuivanen, Elisa Nauha, Jere Ojanen and Kimmo Urtamo.\
Instructions on future development.\
[asdf](asdf)\
University of Jyväskylä, Faculty of Information Technology. 2019.

#- {id="VbqKPiTMjWKT"}