Skip to content

Commit

Permalink
Merge pull request #275 from leeyjjoel/updateDevGuide
Browse files Browse the repository at this point in the history
Update Developer Guide and PPP
  • Loading branch information
thanh-ntt authored Nov 12, 2018
2 parents dc71e94 + 5ec1697 commit b7f0251
Show file tree
Hide file tree
Showing 4 changed files with 81 additions and 52 deletions.
63 changes: 42 additions & 21 deletions docs/DeveloperGuide.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,8 @@ The user executes `newcard q/Hello? a/World` to add a new card with question "He

The following sequence diagram shows how the `newcard` operation works:

image::NewcardSequenceDiagram.png[width="790", align="left"]
image::NewCard Sequence Diagram.png[width="790", align="left"]


==== Design consideration

Expand All @@ -221,25 +222,7 @@ image::NewcardSequenceDiagram.png[width="790", align="left"]
** Cons: The logic for executing deck-level and card-level commands are implemented at different places. We must ensure that the implementation of each command is correct.

// end::cardleveloperation[]
// tag::deckleveloperation[]
=== Deck-level operations
The following deck level operations are supported in Anakin:

* Anakin#newDeck()
* Anakin#removeDeck()
* Anakin#updateDeck()
* Anakin#importDeck()
* Anakin#exportDeck()

The following sequence diagram describes how the editdeck command would work: +
Step 1: +
Step 2: +
Step 3: +

* *Alternative 1* : <Insert first option here>
* *Alternative 2* : <Insert Alternative here>

// end::deckleveloperation[]

// tag::handleinvalidcommands[]
=== Handle invalid commands
Expand Down Expand Up @@ -557,8 +540,6 @@ The logic behind autocompletion is handled by an `Autocompleter` class.
On pressing `<TAB>`, Command Box will raise an event and check if the current text in the command box is autocompletable, that is to say, it is a prefix of one of the existing commands supported by Anakin.
If it is Autocompletable, Autocompleter will search through the list of existing commands in lexicographic order and find the first match for the current text in the command box.

Here is a sequence diagram of what happens during the autocompletion.

==== Design considerations

* *Alternative 1 (current choice):* Use a set of pre-decided completion text for each command and have a list of all supported command words
Expand Down Expand Up @@ -591,6 +572,46 @@ With that, you're good to go!

// end::autocompleteimplementation[]

// tag::scheduling[]

=== Card Scheduling implementation
==== Current implementation (v1.4)

The logic behind scheduling is handled in `Card.java`. Each card contains a `reviewScore` and `nextReviewDate` fields which determine how well the user remembers the card and when the user should review the card again.
When each card is classified using `classify`, it's score is adjusted according to a modified version of the Super Memo 2 algorithm which we have detailed below. The review score is then updated, and using this review score
days are added to the current review date of the card to determine when it should be reviewed.

==== Design considerations

* *Alternative 1 (current choice):* Implement the scheduling update by attaching the scheduling process to the card class
** Pros: As only cards are meant to be scheduled, this will increase cohesion by strengthening the relationship between cards and the scheduling process.
** Cons: Should there be a need to implement scheduling of decks, then we will need to refactor our code for scheduling.

* *Alternative 2:* Create a separate scheduler class to handle performance operations.

** Pros: This will allow us to schedule multiple type of objects.
** Cons: This will decrease cohesion of the components as we only intend for cards to be scheduled in this application.

==== Scheduling Algorithm details
* The variant of the Super Memo 2 algorithm which we have implemented in this application works as follows:

image::SuperMemoTwo.png[width="800"]

Image : A description of the Super Memo 2 variant we implemented. Formula taken from http://www.blueraja.com/blog/477/a-better-spaced-repetition-learning-algorithm-sm2[Blue Raja's blog] +

*Performance Rating*: +
How the user assesses his/her performance during classify. +
`easy` corresponds to a 0 before scaling +
`normal` corresponds to a 1 before scaling +
`hard` corresponds to a 2 before scaling +

*Easiness Score* : This corresponds to `reviewScore` in our implementation

As we only have three levels of difficulty, we have added a `BIAS` term to scale the `reviewScore`.

// end::scheduling[]





Expand Down
13 changes: 8 additions & 5 deletions docs/UserGuide.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -501,7 +501,7 @@ Hit <TAB> for autocompletion so you don't have to remember verbose commands. If

Examples: +

1. Suppose you're attempting to create a new card.
1. Suppose you are attempting to create a new card.

image::newCardPreAutocomplete.png[width="500"]

Expand All @@ -515,15 +515,18 @@ Image: After pressing <TAB> the command is automatically completed!

[NOTE]
====
If the command box is empty autocompletion will default to ``cd 1``.
Additionally, this feature does not work with trailing or preceding whitespace currently.
If the command box is empty, autocompletion will default to ``cd 1``.
====
[WARNING]
====
This feature does not work when trailing or preceding whitespace is included in the command.
====

// end::autocompletion[]

// tag::rank[]
=== Rank : `rank`

To sort all cards by a user's cumulative performance score on each card. +
Use this command to sort all cards by a user's cumulative performance score on each card. +
Format: `rank` +
Examples: Suppose you are studying for an important exam, and you want to find out which cards you performed poorly on so you can review them.

Expand Down
Binary file added docs/images/SuperMemoTwo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
57 changes: 31 additions & 26 deletions docs/team/leeyjjoel.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,17 @@ This portfolio outlines my contributions to the following project.
---

Anakin is the result of our search for a better command line application to revise for exams. From August 2018 to November 2018,
Team T09-2 comprising of myself, Tay Yu Jia, Foo Guo Wei, David Goh and Nguyen Truong Thanh built Anakin as part of a Software Engineering module (CS2103T) conducted at
Team T09-2 comprising of myself, Tay Yu Jia, Foo Guo Wei, David Goh, and Nguyen Truong Thanh built Anakin as part of a Software Engineering module (CS2103T) conducted at
the National University of Singapore.

== Overview

Anakin is a desktop-based flashcard application which makes remembering things easy. The user
interacts with it using a Command Line Interface but can fallback to the Java FX GUI if needed. Anakin uses https://www.supermemo.com/english/ol/sm2.htm[Super Memo 2] which is the spaced repetition algorithm used by popular language learning tools such as
interacts with the application primarily using a Command Line Interface. However, the user can fall back to the Java FX GUI if needed. Anakin uses https://www.supermemo.com/english/ol/sm2.htm[Super Memo 2] which is the spaced repetition algorithm used by popular language learning tools such as
Duolingo, Wani Kani, and Memrise. +

Anakin aims to revolutionise the studying experience of the technically advanced user. On top of being easy to use,
Anakin is also environmentally friendly, having zero paper wastage unlike conventional flashcards.
Anakin aims to revolutionize the studying experience of the technically advanced user. On top of being easy to use,
Anakin is also environmentally friendly, having zero paper wastage, unlike conventional flashcards.

image::Ui.png[width="500"]
[NOTE]
Expand All @@ -41,19 +41,19 @@ It is written in Java, and has about 10 kLoC.

== Summary of contributions

This section acts as a summary of the contributions made by Lee Yi Jie Joel to project Anakin.
This section acts as a summary of my contributions to project Anakin.

* *Major enhancement*: I added autocompletion for commands
** What it does: allows the users to sort cards by when they should be reviewed.
** What it does: Helps a user complete a partially typed command
** Justification: This feature improves the product significantly because a user will want to be able to finish expressing
the command he wants to type with a simple press of <TAB>
** Highlights: This enhancement affects existing commands and commands to be added in future. While typing in the command box, the student is saved from the hassle of typing and remembering
long strings of command syntax. This will allow for a better user experience and in turn easier studying for tests.
** Highlights: This enhancement removes the need for the user to memorise long strings of command syntax. While typing in the command box, the user is saved from the hassle of checking the user guide
for commands he/she has forgotten. This will allow for a better user experience and in turn easier studying for tests.

* *Major enhancement*: I added the scheduling algorithm at the core of the product together with the `rank` command
** What it does: allows the users to sort cards by when they should be reviewed.
** Justification: This feature improves the product significantly because a user will want to review cards which he or she performed poorly on
** Highlights: This allows user to focus on what's important for review by sorting the cards in order of performance and pushing cards which require review to the top of the deck.
** What it does: allows the users to sort cards by performance during review. Cards which the user has performed poorly on will be pushed to the top of the deck.
** Justification: This feature improves the product significantly because a user will want to review cards which he or she performed poorly on to increase the yield of her revision.
** Highlights: This allows user to focus on what's important to review and makes for more efficient study sessions.



Expand All @@ -72,45 +72,48 @@ https://nus-cs2103-ay1819s1.github.io/cs2103-dashboard/#=undefined&search=leeyjj
* *Other contributions*:

** Project management:
*** Set up Continuous Integration:
https://github.com/CS2103-AY1819S1-T09-2/main/issues?q=is%3Aissue+is%3Aclosed+author%3Aleeyjjoel[List of created issues]
*** Update contact us page (Pull request https://github.com/CS2103-AY1819S1-T09-2/main/pull/68[#68])
*** Added initial documentation for team README (Pull request https://github.com/CS2103-AY1819S1-T09-2/main/pull/23[#23])
*** Integrate Reposense for code contribution tracking (Pull request https://github.com/CS2103-AY1819S1-T09-2/main/pull/75/files[#75])
*** Configure naming convention of files and packages across the project to comply with project style guide(https://github.com/CS2103-AY1819S1-T09-2/main/pull/38/files[#38]
*** Set up Continuous Integration
*** Update contact us page (Pull Request: https://github.com/CS2103-AY1819S1-T09-2/main/pull/68[#68])
*** Added initial documentation for team README (Pull Request: https://github.com/CS2103-AY1819S1-T09-2/main/pull/23[#23])
*** Integrate Reposense for code contribution tracking (Pull Request: https://github.com/CS2103-AY1819S1-T09-2/main/pull/75/files[#75])
*** Configure naming convention of files and packages across the project to comply with project style guide(Pull Requests: https://github.com/CS2103-AY1819S1-T09-2/main/pull/38/files[#38]
, https://github.com/CS2103-AY1819S1-T09-2/main/pull/106/files[#106])



** Enhancements to existing features:
*** Wrote extensive system tests which played a major role in boosting coverage from 66% to the above 90%
*** Wrote extensive system tests which played a major role in boosting coverage from 66% to the above 90%. The tests I have written are detailed below:
**** Wrote integration tests and tests for help command(https://github.com/CS2103-AY1819S1-T09-2/main/pull/148[#148])
**** Wrote Unit Tests for editdeck(https://github.com/CS2103-AY1819S1-T09-2/main/pull/121/files[#121])
**** Wrote tests for EditCard, EditDeckParser, and GUI (https://github.com/CS2103-AY1819S1-T09-2/main/pull/157/files[#157])
**** Wrote System Tests for ClearCommand, FindCommand, Logic Manager, EditDeck, NewDeck(https://github.com/CS2103-AY1819S1-T09-2/main/pull/158/files[#158],
**** Wrote Unit Tests for editdeck(Pull Request: https://github.com/CS2103-AY1819S1-T09-2/main/pull/121/files[#121])
**** Wrote tests for EditCard, EditDeckParser, and GUI(Pull Request: https://github.com/CS2103-AY1819S1-T09-2/main/pull/157/files[#157])
**** Wrote System Tests for ClearCommand, FindCommand, Logic Manager, EditDeck, NewDeck(Pull Requests: https://github.com/CS2103-AY1819S1-T09-2/main/pull/158/files[#158],
https://github.com/CS2103-AY1819S1-T09-2/main/pull/165/files[#165],
https://github.com/CS2103-AY1819S1-T09-2/main/pull/238[#238], https://github.com/CS2103-AY1819S1-T09-2/main/pull/242[#242], https://github.com/CS2103-AY1819S1-T09-2/main/pull/244[#244])


** Documentation:
*** Add documentation for deck level operations(https://github.com/CS2103-AY1819S1-T09-2/main/pull/110/files[#110])
*** Update user guide and development guide(https://github.com/CS2103-AY1819S1-T09-2/main/pull/268[#268])
*** Add documentation for deck level operations(Pull Request: https://github.com/CS2103-AY1819S1-T09-2/main/pull/110/files[#110])
*** Update user guide and development guide(Pull Request: https://github.com/CS2103-AY1819S1-T09-2/main/pull/268[#268])

** Community:
*** PRs reviewed (with non-trivial review comments):
*** Pull Requests reviewed(with non-trivial review comments):
https://github.com/CS2103-AY1819S1-T09-2/main/pull/189[#189]
https://github.com/CS2103-AY1819S1-T09-2/main/pull/195[#195]
https://github.com/CS2103-AY1819S1-T09-2/main/pull/271[#271]

*** Discovered and reported bugs to peers:
https://github.com/CS2103-AY1819S1-T09-2/main/issues?q=is%3Aissue+is%3Aclosed+author%3Aleeyjjoel[List of created issues]



== Contributions to the User Guide

|===
|_Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users._
|===

include::../UserGuide.adoc[tag=autocompletion]
include::../UserGuide.adoc[tag=rank]
include::../UserGuide.adoc[tag=undoredo]


== Contributions to the Developer Guide
Expand All @@ -120,8 +123,10 @@ include::../UserGuide.adoc[tag=undoredo]
|===

include::../DeveloperGuide.adoc[tag=autocompleteimplementation]
//include::../DeveloperGuide.adoc[tag=deckleveloperation]
include::../DeveloperGuide.adoc[tag=scheduling]

== Additional Information
For more information about me and to view more of my works, please feel to check out my website https://joellee.ml[here]



0 comments on commit b7f0251

Please sign in to comment.