1. Introduction

This project portfolio page displays my contributions to the BrainTrain project.

1.1. Overview

The BrainTrain project was designed, developed and implemented by a team of 5 students over seven weeks, under one of the National University of Singapore’s modules: CS2103T Software Engineering.

We chose to morph existing addressbook application into a spaced-repetition system flashcard application to improve our software engineering skills and build an application for users who need to memorize heavy contents.

1.2. What is BrainTrain

BrainTrain is an open-source spaced repetition flashcard application for people who need to memorise something which is content heavy. Research has shown that the Spaced-Repetition System (SRS) is much more effective than traditional memorization techniques since it help users review more their poorly memorised words. With BrainTrain, you will learn more with less time since this application makes memorizing an easier and more efficient job.

BrainTrain is also a portable and easy-to-navigate desktop program. It is an offline application which you can use anywhere, even in places with limited or no Internet availability. It can be navigated and used via easy-to-use commands through the Command Line Interface (CLI). The CLI is supplemented by a minimalistic Graphical User Interface (GUI) which provides helpful but non-distracting visual aid. Together, the CLI and GUI provides an effective and straightforward way for you to use BrainTrain.

1.3. My role

My role was to design and write the codes for a session feature as well as start command. The following sections illustrate these enhancements and other relevant minor enhancements in more detail.

2. Summary of contributions

This section shows a summary of my coding, documentation, and other helpful contributions to the team project.

2.1. Major enhancement: Session and session manager model

  • What it does: Session model generates quiz cards that are needed to be tested in quiz mode based on data storage both from lesson and user progress.

  • Justification: To choose the most suitable words for users, session model also has a manager to do the card analysis and generation based on different modes that users want. In review mode, the method will always generate the cards with the closet due date to users which applies our spaced-repetition system. It can update the user progress after each quiz session as well.

  • Highlights: Pull request #40, #97, #109 and #132.

  • Code contributed: [RepoSense]

2.2. Minor enhancement: quiz start command

  • What it does: Users can start a quiz session using start command.

  • Justification: Users can specify the lesson and number of cards they want to be tested as well as the quiz mode they want to enter through setting different parameters in the quiz start command .

  • Highlights: Pull request #40, #100 and #185.

  • Code contributed: [RepoSense]

2.3. Other contributions:

Besides designing and writing codes, I also contributed to the project in the following areas:

  • Documentation:

    • Updated explanation and diagrams in user guide and developer guide to match the current implementation.

    • Sorted out and updated use stories and cases in develop guide. (Pull request #14)

  • Enhancement to existing feature:

    • Updated the Graphical User Interface representation for the quiz system. (Pull request #176)

  • Project management:

    • Followed team’s internal schedule and updated the codes before each milestone.

  • Community:

    • PRs reviewed with comments: (examples: Pull request #86, #107)

    • Reported bugs and offered suggestion for the project. (examples: #98, #128)




3. Contributions to the User Guide

Given below are sections I contributed to the User Guide, showing development that I have made for the start feature. They showcase my ability to write documentation targeting end-users.

The sections also contain an excerpt for the starting multiple lessons feature that I have planned for the next version (v2.0) of BrainTrain.

3.1. Starting a quiz session: start

Starts a new quiz session.
Format: start LESSON_INDEX [c/COUNT] m/MODE

This command only works in lesson view. If you are currently editing a lesson in card view, you have to use the quit command to return to lesson view before you can use this command.

Usage rules:

  • You must specify the index of lesson to be started. If your input index is out of range of current Lesson List, an error will be thrown.

  • You can optionally specify the COUNT parameter. COUNT sets the number of cards to be tested in the quiz session.

    • If no COUNT is specified, by default 1 card is tested.

    • If COUNT is larger than the size of the current lesson, the COUNT will be reset to be the size of the lesson by default.

  • You must specify index and count as a valid number which should be less than the MAXIMUM_INTEGER(0*7ffffffff), otherwise an error will be thrown.

  • You must specify MODE. MODE sets the testing mode of the quiz session. The four available modes are LEARN, PREVIEW, REVIEW and DIFFICULT.

    1. LEARN: Displays new cards with both question and answer before test begins, and then only question is shown to test you. If you have already learned all the cards in current lesson, an error of no more new card to learn will be thrown.

    2. PREVIEW: Displays both question and answer of cards. You will not be tested.

    3. REVIEW: Tests the words based on the spaced-repetition algorithm, which means that cards with the earliest test date are tested first. If no card has due date before current time, an error of no card for review will be thrown.

    4. DIFFICULT: Displays cards you previously labelled as difficult with both question and answer shown. You will not be tested. If no card has been labelled as difficult, an error of no difficult card will be thrown.

Only in review mode, cards are tested based on the Space-Repetition system.

Examples:

  • start 1 m/LEARN
    Starts a quiz in LEARN mode. Cards will be chosen from the first lesson in lesson list. Since count is not specified, the quiz will only contain one card by default.

  • start 2 c/20 m/PREVIEW
    Starts a quiz containing 20 cards chosen from the second lesson in lesson list in PREVIEW mode, which only displays question and answer together one time.

After you start a quiz session with the start command, BrainTrain will switch to quiz mode and you will only be allowed to enter quiz mode commands.

3.2. Supporting starting a quiz session with multiple lessons [Coming in v2.0]

  • Format: start LESSON_INDEX_1 LESSON_INDEX_2 [c/COUNT1] [c/COUNT2] m/MODE

  • You can start a quiz session with cards from more than one lesson. The sequence of cards will be random instead of following the sequence of lessons to increase the difficulty for you to memorize.

  • Example: start 1 2 c/5 c/5 m/learn

    • Starts a quiz with 5 words from the first lesson and 5 words from the second lesson in LEARN mode.




4. Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide, showing implementation I have made for the session feature as well as some suggested test cases for StartCommand. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

4.1. Session feature

Session feature generates cards for users in quiz session based on their requirement.

4.1.1. Current implementation

Session feature implements the following functions and commands:

  • Combining data from lesson and user storage together.

  • SrsCardManager:

    • Generating a list of cards for quiz based on different modes and SRS (Space-Repetition technique) method.

    • Updating user data after quiz ends.

  • start - An input with lesson index, count of cards and mode parameters.

4.1.2. SRS method

The SRS method allows users to be tested with the most urgent questions. The method gives each card a srsDueDate field which contains an instant value representing the deadline of testing this card again.

  • The SRS method updates users profile using Leitner_system.

    • There are several levels in the Leitner_system. The lower the level is, the more urgent the card is. When the user answers correctly, the level of that card will increase by one. Otherwise it will decrease by one.

    • User data will be updated based on their performance in quiz session. Generally speaking, if the user answer correctly, the srsDueDate of the current card will be carry-forwarded.

Leitner system
Figure 1. Explanation diagram for Leitner-System

4.1.3. SrsCardManager

The SrsCardManager generates needed list of QuizCard when the user wants to start a quiz. This class includes four methods for four different modes correspondingly as shown below.

  • Difficult mode: previewDifficult()

  • Preview mode: preview()

  • Learn mode: learn()

  • Review mode: sort()

The following activity diagram summarizes what happens when the user executes a new StartCommand.

SrsCardManagerGenerateActivityDiagram
Figure 2. Activity diagram for session generation

Space-Repetition technique is only applied in review mode.

The SrsCardManager also updates user data using UpdateCardData() after receiving results from Quiz.

4.1.4. Management start command: start

The start command starts a quiz session based on input parameters. It will analyze the current storage information and then generate the list of QuizCard using SrsCardManager. It will test the 2 values set to be tested for the lesson. The generating rules are different for different QuizMode as explained in a subsequent section. Once the start command have succeeded running, the system will switch to the quiz mode.

The start command needs users to specify LessonIndex, CardCount and QuizMode parameter.

The following sequence diagram shows the interaction between the various classes when the user starts a sample quiz:

QuizStartCommandSequenceDiagram
Figure 3. Sequence diagram for start feature

4.1.5. Design consideration

Aspect: SRS method for updating

  • Alternative 1: Leinter System (current choice)

    • Pros: Efficient in calculation and easy to understand.

    • Cons: The time interval between levels cannot be long.

  • Alternative 2: Pimsleur’s graduated-interval recall

    • Pros: Short time interval between the first few repetitions.

    • Cons: No level attribute to group the element clearly.

  • Alternative 1 was chosen because it clearly displays the due date in several levels. Developers can also understand it easily since the actions for updating is simple. Besides, the system does not require the testing interval of the same card to be very small.

Aspect: data storage to support the SRS system

  • Alternative 1: The system saves the due time into several levels and stores in a hashmap with card’s hashcode (current choice)

    • Pros: It is easier to update the user progress using Leinter System since the levels are already stored.

    • Cons: The system needs to generate the range of due time for each level by default and the range may be unreasonable.

  • Alternative 2: The system saves the due time and hashcode of cards directly in a 2D array

    • Pros: It is clearer to see the match between card and its due time with same hashcode.

    • Cons: It is more difficult to set the updated due time for each single card.

  • Alternative 1 was chosen because the quiz only passes back information of total attempts and total number of correct answers. It is hard to generate an algorithm to update due time for each single card with only these quiz information. Thus, grouping cards as different levels and updating due time under different levels can solve this problem more efficiently.

Aspect: review mode

  • Alternative 1: Starts test directly (current choice)

    • Pros: Users can focus on the tests directly.

    • Cons: No time for them to have a quick reminder.

  • Alternative 2: Starts with previewing questions and answers

    • Pros: Users can recall the cards before testing.

    • Cons: The difficulty level becomes lower.

  • Alternative 1 was chosen because users are supposed to enter the test directly when they are reviewing cards. They can then judge their memorizing results in a most accurate level.

4.2. Starting a new quiz

Below are some test cases you can perform to test the StartCommand for the Management feature.

  1. Prerequisite: The system is in the management mode and there is no opened lesson currently.

  2. Test case:

    1. start 1 m/preview
      Expected: The system and GUI change to Quiz mode. Starting new quiz. Current lesson is the first lesson in the list. Besides, only one card will be previewed in the quiz.

    2. start 3 c/1 m/learn
      Expected: The system and GUI change to Quiz mode. Starting new quiz. Current lesson is the third lesson in the list. Besides, only one card will be learnt in the quiz.