By: CS2103-AY2018/19s2-W10-4 Team Since: Mar 2019 Licence: MIT

1. Introduction

Know-It-All is a flashcard application that helps users store and organise their learning material. With an easy to use interface and convenient content sharing functionality, Know-It-All is designed to help students perform rote learning more efficiently. From cramming in between lessons to focused study, the interactive test session boosts the effectiveness of repetition and recall for memorisation. Know-It-All targets medicine students as their studies involve a considerable amount of memory work, and deals with content that is suitable for the bite-sized flashcard format.

Ui

2. How To Use This Guide

Welcome to the Know-It-All User Guide! This document will equip you with what you need in order to use v1.4 of the application. While some familiarity with command line programs will come in handy, simply adhere to the command formats specified in this guide closely and the rest will be a breeze.

Look out for the following icons and formatting used!

Important information that should be noted.
Tips that can help if you get stuck.

test: Command to be executed or less commonly, a component, class or object in the architecture of the application.

Useful information for a deeper understanding of the command.

Without further ado, let’s head over to Section 3, “Quick Start” to get started!

3. Quick Start

3.1. Launching the application

To get Know-It-All up and running:

  1. Ensure that you have Java version 9 or later installed in your Computer.

  2. Download the latest knowitall.jar here.

  3. Copy the file to the folder you want to use as the home folder for Know-It-All.

  4. Double-click the file to start the app. The GUI should appear in a few seconds.

3.2. Using the application

In this section, we’ll walk you through the primary user interface of the application and how to create your first flashcard.

To use a command, type the command in the command box and press enter to execute it.
e.g. typing help and pressing enter will open the help window.

  1. When booting up the app for the first time, you should see the home directory much like the screengrab below. The first and only folder present is a sample folder.

    AnnotatedStartupUI

  2. cd 1 : enters the 1st flashcard folder. You will see a change in the user interface as you enter the folder.

    AnnotatedEnterFolderUI

  3. add q/How many chambers are there in a heart? a/Four : adds a new flashcard to the current folder.

    AnnotatedAddCardUI

  4. select 4 : selects the 4th flashcard in the current folder, which is also your newly added card.

    AnnotatedSelectCardUI

  5. exit : exits the app. The app window will close.

This is the end of the Quick Start tutorial. Please refer to Section 4, “Features” for details of each command, and feel free to reach out to us if you run into any issues!

Your data is saved in the data/ folder by default. Like any other software application, you are not advised to modify any of the system created files located within the folder. If you do, Know-It-All may not perform right!

4. Features

Command Format

  • Commands are written in monospaced font, e.g. sort

  • Words in UPPER_CASE are the parameters to be supplied by you e.g. in addfolder FOLDER_NAME, FOLDER_NAME is a parameter which can be something like Human Anatomy.

  • Items in square brackets are optional e.g HINTS in add q/QUESTION a/ANSWER [h/HINTS].

  • Items with …​ after them can be used multiple times including zero times e.g. in add q/QUESTION a/ANSWER [i/INCORRECT_OPTION]…​, you can include zero or more i/INCORRECT_OPTIONs.

  • Parameters can be in any order e.g. if the command specifies q/QUESTION a/ANSWER, a/ANSWER q/QUESTION is also acceptable.

This application only supports Unicode characters compatible with XML. In general, most characters visible on your keyboard are supported! Please refer to here for more details on incompatible characters.

4.1. Folder Operations

Commands listed in this section are folder-level operations. This includes the operations such as creating and deleting of folders, and excludes commands that affect the contents of individual folders (e.g. adding a card).

The commands in this section, unless otherwise stated, can only be executed when you are at the home directory, outside of any folder. The commands are also not valid inside a test or report session. You can easily verify that you are at the home directory with the status bar at the bottom, which should display:

StatusBarInHomeDirectory

4.1.1. Enter folder : cd

Enters the folder specified by index. Panel on the left will display the list of cards in that folder.

Format: cd FOLDER_INDEX

Examples:

  • cd 2
    Enters the second folder in the folder list on the home directory.

4.1.2. Exit folder : cd ..

Return to the root directory (exit the current folder). A list of folders will be displayed

Format: cd ..

  • This command, unlike the rest of the commands in this section, can only be executed when inside a folder.

Examples:

  • cd 2
    cd ..
    The first command enters the second folder in the folder list on the home directory. The second command then returns you back to the home directory by exiting the folder.

4.1.3. Create new folder : addfolder

Creates a new flashcard folder with the specified name.

Format: addfolder FOLDER_NAME

  • The newly created folder will not contain any cards.

  • Folder names must be unique, between 1 and 50 characters, and only contain letters, numbers and whitespace. Folder names with the same characters but different capitalisation are non-unique. Attempting to add a folder with any of the above rules violated will result in an error.

  • Each folder and its cards are stored independently in the directory specified in preferences.json. By default, this is the data/ directory.

Examples:

  • addfolder Nervous System
    Creates a folder with the name "Nervous System". The UI should appear like the following after the command is executed.

AnnotatedAddFolderUI

You can then enter the folder with the cd command and begin adding cards.

4.1.4. Remove folder : deletefolder

Removes the flashcard folder specified by index.

Format: deletefolder FOLDER_INDEX

  • When a folder is deleted, all its cards are removed as well.

Examples:

  • deletefolder 2
    Deletes the second folder in the folder list, along with its cards, on the home directory.

4.1.5. Rename folder : editfolder

Renames the flashcard folder specified by index.

Format: editfolder FOLDER_INDEX NEW_FOLDER_NAME

  • The new name of the folder cannot be the same as an existing folder, and must adhere to the rules specified in Section 4.1.3, “Create new folder : addfolder”.

  • You are allowed to rename an existing folder to a different capitalisation of its own name.

Examples:

  • editfolder 2 Circulatory System
    Renames the second folder in the folder list to "Circulatory System".

Merge folders feature Coming in v2.0

This feature will enable users to join multiple folders together, reducing the number of folders and grouping two topics.

Format: merge FOLDER_INDEX_1 FOLDER_INDEX_1 NEW_FOLDER_NAME

4.2. Card Operations

Commands listed in this section affect the flashcards within a single folder.

The commands in this section can only be executed when you are within a folder. The commands are also not valid inside a test or report session. You can easily verify you are inside a folder with the status bar at the bottom, which should display:

StatusBarInFolder

4.2.1. Adding a flashcard : add

Adds a flashcard to the current folder. Know-It-All supports 2 types of flashcards: Single answer cards and MCQ cards.

Format (Single answer): add q/QUESTION a/ANSWER [h/HINT]
Results in the following card:
singleAnswerCard

Format (MCQ): add q/QUESTION a/ANSWER [i/INCORRECT_OPTION]…​ [h/HINT]
Results in the following card:
mcqCard

  • The question, answer, incorrect option, and hint fields can take any character, but cannot be blank.

  • Each question, answer, incorrect option and hint must be 256 characters or less (including spaces).

  • If the card to be added has the same question and answer as an existing card, the card to be added will be considered a duplicate card, and the add attempt will be invalid.

  • A card can have at most 1 hint (including 0).

  • A card can have at most 3 incorrect options to denote an MCQ card.

  • A card with 0 incorrect options will automatically be denoted as a Single answer card.

  • If the content of a card exceeds the length of the card, you can scroll/click and drag to see the rest of the content.

Examples:

  • add q/Hello? a/World

  • add q/The cat _ on the mat a/sat h/poetry

  • add q/What is the powerhouse of the cell? a/mitochondria i/cell wall i/nucleus h/biology

Adding Fill-In-The-Blanks style card Coming in v2.0

Allows you to add a card with blanks for multiple answers to be given during a test session. Questions for such cards would include underscores "_", each signifying a blank to be filled with an answer.

Format: `add q/QUESTION_WITH_BLANKS a/ANSWER_1/ANSWER_2/ANSWER_3…​

Example:

  • add q/The quick brown _ jumps over the lazy _. a/fox/dog

Adding images to cards Coming in v2.0

Allows you to add images to cards to supplement the text content of the card.

Format: add q/QUESTION a/ANSWER [img/IMAGE_FILE_PATH]…​

Example:

  • add q/Hello? a/World img/diagram.jpg

4.2.2. Editing a flashcard : edit

Edits the flashcard specified by the index in the current folder.

Format: edit INDEX [q/QUESTION] [a/ANSWER] [h/HINT]

  • Edits the card at the specified INDEX. The index refers to the index number shown in the displayed card list. The index must be a positive integer 1, 2, 3, …​

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • (MCQ cards) When editing incorrect options, the existing incorrect options of the card will be removed i.e adding of options is not cumulative.

  • You can remove the card’s hint by typing h/ without specifying any hint after it.

  • You can remove the card’s incorrect options by typing i/ without specifying any incorrect option after it.

Examples:

  • edit 1 a/Skin h/
    Edits the answer of the 1st card to be 'Skin' and removes the hint associated, if any.

  • edit 2 h/history q/Who discovered Penicillin? a/Alexander Fleming
    Edits the hint, question and answer of the 2nd card respectively.

  • edit 3 h/cells h/biology h/organs
    Replaces the hint of the current card with "organs" only.

4.2.3. Selecting a flashcard : select

Displays flashcard details (question, answer, hint, card score) on the right panel on selection by index.

Format: select INDEX

Examples:

  • list
    select 2
    Selects the 2nd card in the current folder

4.2.4. Deleting a flashcard : delete

Deletes the flashcard identified by index from the current folder.

Format: delete INDEX

  • Deletes the card at the specified INDEX.

  • The index refers to the index number shown in the displayed card list.

  • The index must be a positive integer 1, 2, 3, …​

  • list
    delete 2
    Deletes the 2nd card in the address book.

4.2.5. Sort flashcards by score within a folder : sort

Displays all flashcards sorted such that the lowest card scores are at the top temporarily.

Format: sort

4.2.6. Search by keywords : search

Within a folder, searches for flashcards inside the current folder using keywords in flashcard questions.

Format: search KEYWORDS [MORE_KEYWORDS]

4.2.7. List flashcards : list

Display a list of the flashcards in the current folder, where only questions can be seen, answers are hidden.

Format: list

  • This command is implicitly invoked upon entering a folder, and can be used to reset the view after search or sort.

4.2.8. Undoing previous command : undo

Restores the cards in a particular card folder to the state before the previous undoable command was executed.

Format: undo

  • This command is performed with respect to the present folder you are in. For example, if you perform an add operation in folder A and enter folder B, invoking the undo command will undo the previous undoable command performed in folder B and not the aforementioned add operation.

Undoable commands: commands that modify a card folder’s content (add, delete and edit).
At the end of a successful test session, scores are final and you will not be able to perform an undo to restore the previous states before the test session.

Examples:

  • delete 1
    list
    undo (reverses the delete 1 command)

  • select 1
    list
    undo
    The undo command fails as there are no undoable commands executed previously.

  • delete 1
    clear
    undo (reverses the clear command)
    undo (reverses the delete 1 command)

4.2.9. Redoing the previously undone command : redo

Reverses the most recent undo command performed in a folder.

Format: redo

  • As with the undo command, this command is performed with respect to the present folder you are in. For example, if you perform an undo operation in folder A and enter folder B, invoking the redo command will redo the previous undo command performed in folder B and not the one in folder A.

Examples:

  • delete 1
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)

  • delete 1
    redo
    The redo command fails as there are no undo commands executed previously.

  • delete 1
    clear
    undo (reverses the clear command)
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)
    redo (reapplies the clear command)

4.2.10. Export flashcards : export

Exporting flashcards is a great way to start sharing your flashcards with others.

The export command creates a csv file containing the flashcards from the specified folder in your project root directory.

Format: export FOLDER_INDEX FILENAME [MORE_INDEXES]

The export command creates the new csv file in your project root directory. i.e The directory where your .jar file is located.
The import command imports csv files located in the same directory as well.
project root dir
The current version does not support the importing and exporting of files outside of this directory

  • You should key in indices corresponding to the folder index

  • Negative numbers are not allowed

Examples:

  • export 1 2 3
    exports the first, second and third cardfolder in your home directory. Suppose that the first, second and third cardfolder corresponds to the card folder names :
    Blood
    Circulatory System
    Cardiovascular
    Then the following files Blood.csv, Circulatory System.csv and Cardiovascular.csv will be created in the project root directory.

4.2.11. Import flashcards : import

Besides being able to import flashcards exported by others, the import command provies a faster way of creating multiple flashcards.

You type your flashcards out on excel and later save it in your project root directory, allowing you to import it over to your application.

The csv file imported should follow the format described below

  • The first row of the csv file should have the following headers:

    Question, Answer, Hints, Option, Option, Option.

  • Question and Answer are mandatory fields, and should not be left blank.

  • Hints can take 0 or 1 values only.

  • For MCQ cards, The csv file accepts up to 3 incorrect options per flashcard.

Blood
Figure 1. Sample format for csv file

Format: import FILENAME

unlike the export command the importing of multiple csv files is not supported in Know-It-All.
Filename imported is case insensitive.

Examples:

  • import Blood.csv
    Imports blood csv file into Know-It-All. A new Blood cardfolder should be present in the home directory after execution of this command.

4.3. Test Operations

After memorising the content of the flashcards, it is helpful to test how much information have been internalised and retained in a timed setting. The following commands show just how this can be done with the Test Session functionality of Know-It-All.

At the end of a successful test session, scores are final and you will not be able to perform an undo to restore the previous states before the test session.

4.3.1. Test flashcards in a folder : test

You will enter a test session, where the display area enters a fullscreen and you will be presented flashcard questions and hints (if any) one by one. You should see a screen like the figure below.

startTestSessionPage
Figure 2. A successful test command will display a test session page


Format: test

This command is only considered valid when inside the folder to be tested and is not already inside a test session.
This command is invalid if the current folder is empty as there will be no flashcards to test.

  • Hints will be presented along with the questions.

  • When presented with a question in a test session, you can either input an attempt or enter the command to reveal the answer.

  • For MCQ cards, the ordering of options will be randomized each time the flashcard is tested.

  • Internally, flashcards in a folder are queued to be displayed one by one in the order of lowest existing score to highest existing score.

  • The next flashcard will only be presented when the next command is carried out.

Examples:

  • test

Hint toggle on / off feature Coming in v2.0

If you are familiar with the content and feeling confident, simply toggle off hints during the test session. You can do it by specifying ‘-nohint’ at the end of the test command. Hint will not be displayed along with the question when the card is presented.

Format: test [-nohint]

Timer feature Coming in v2.0

If you are preparing for an exam that will require you to recall information quickly within the limited time given, this timer feature is just right for you! You will be given only 20 seconds to answer each question. If the 20 seconds is up before the question is answered, this attempt will be marked as wrong.

Format: test [-timer]

4.3.2. Keying in answer to a flashcard: ans

To reinforce learning and provide a more engaging experience with Know-It-All, you can input an answer for the currently displayed flashcard question. Know-It-All compares your attempt with the correct answer for that flashcard and tells you if you are right or wrong.

If the answer has been submitted successfully and it is correct, you will see the following page.

CorrectAnswerPage
Figure 3. Correct Answer page


If the answer has been submitted successfully and it is wrong, you will see the following page.

WrongAnswerPage
Figure 4. Wrong Answer page


Format: ans ANSWER

This command is only considered valid if a card question is currently being displayed in an active test session.

  • Answer matching is case insensitive.

  • Answering a flashcard will increase the total number of attempts. If your answer is correct, this action will also increase the number of correct attempts.

  • To answer MCQ cards, enter the number of the option that you think is correct, rather than the option itself.
    E.g. ans 1 rather than ans myanswer

Examples:

  • ans Mitochondrion
    in response to the card question: What is the powerhouse of the cell?

  • ans 2
    in response to the card displayed below, choosing option 2 will give the right answer as the correct answer is 'Pigs'.

AnsweringMcqCard
Figure 5. Answering an MCQ card

4.3.3. Reveal answer to a flashcard : reveal

If you have no clue what the answer is, this command immediately reveals the correct answer, as seen in the figure below. You will not need attempt any answer before being presented the correct answer.

RevealAnswerPage
Figure 6. Revealed Answer page


Format: reveal

This command is only considered valid if a card question is currently being displayed in an active test session.

  • This is equivalent to a wrong answer attempted, so there is no addition to the correct attempts of this card.

4.3.4. Go to next flashcard : next

You will be presented with the next lowest scoring flashcard in this current test session. Upon a successful next command, you should see a similar page below.

NextCommandPage
Figure 7. Next card question displayed upon a successful next command


Format: next

This command is only considered valid if a card question and answer is currently being displayed (has already done answering the question or revealed the answer) in an active test session. In other words, a flashcard cannot be skipped.

  • If all cards have already been tested, a next command will be equivalent to an end command, ending the current test session.

  • There is no backtracking in the current session so there is no prev command.

4.3.5. End the current test session : end

Quits the current test session and you will be back inside the card folder. You should see a page like below.

EndCommandPage
Figure 8. A successful end command brings you back to inside the folder


Format: end

For the final test score to be recorded, you must have attempted at least 1/4 of cards in the card folder. If there are less than 4 cards, any number of cards attempted will be recorded.

4.4. Report Operations

After testing, you can track how you scored against previous attempts using our report feature. Because test sessions are run for cards in a folder, the test scores are tracked per folder.

4.4.1. Display a test score report : report

Displays a full-screen test score report for the current folder. The report comprises a graph showing a maximum of the last 10 test scores, the latest score change, and a maximum of 3 lowest individual scoring cards and their individual card scores. An example is shown below:

ReportDisplay
Figure 9. Report display
The report display is currently best viewed with the window in full screen. Otherwise, you may need to use the horizontal and vertical scroll bars to view the graph and questions. Hang tight, a display that changes in size is coming in v2.0!

Displays response time for each card Coming in v2.0

With the timer feature coming in v2.0, we are also able to track the time taken to provide the correct response to the question. This provides yet another metric, in addition to correctness, to judge your understanding of the topic.

Format: report

This command is only valid inside a folder.

  • There must be at least two test attempts for the line graph to be drawn.

4.4.2. End the current report session : end

Quits the current report session.

Format: end

This command is only valid inside a report display.

4.5. Global operations

These commands are valid from anywhere in the application.

4.5.1. Viewing help : help

Opens the User Guide in a new window.

Format: help

4.5.2. Exiting the program : exit

Exits the program.

Format: exit

5. Glossary

  • Flashcard/Card: An object containing a single question and answer, and optionally hints.

  • Folder: A collections of flashcards. There are no sub-folders.

  • Test Session: A session where all flashcards in a folder are queued to have their questions displayed. You are required to key in an answer for each question.

  • Card Score: The number of correct answers divided by the number of attempts for a single card. When you are tested on a card, this number is automatically calculated and recorded.

  • Test Score: The number of cards correctly answered over number of cards attempted during a test session. This number is automatically recorded after each test session.

  • Home Directory: The home page where all the folders are listed. From here, users can enter folders to view cards.

  • Index: The unique number associated with an item in a list. The first item in a list has an index of 1.

6. Command Summary

Command Summary

add q/QUESTION a/ANSWER [h/HINT] [i/INCORRECT_OPTION]…​

Adds a flashcard to the current folder.

edit INDEX [q/QUESTION] [a/ANSWER] [h/HINT] [i/INCORRECT_OPTION]…​

Edits the flashcard specified by the index in the current folder.

select INDEX

Displays flashcard details (question, answer, hint, card score) on the right panel on selection by index.

delete INDEX

Deletes the flashcard identified by index from the current folder.

sort

Displays all flashcards sorted such that the lowest scoring cards are at the top temporarily.

search KEYWORDS [MORE_KEYWORDS]

Searches for flashcards inside the current folder using keywords in flashcard questions.

list

Display a list of the flashcards in the current folder

report

Display a test score report for the current folder

undo

Undoes the previous undoable command.

redo

Redoes the last undo.

cd ..

Return to the root directory (exit the current folder). A list of folders will be displayed.

cd FOLDER_INDEX

Enters the folder specified by index. Panel on the left will display the list of cards in that folder.

addfolder FOLDER_NAME

Creates a new flashcard folder with the specified name.

deletefolder FOLDER_INDEX

Removes the flashcard folder specified by index.

editfolder FOLDER_INDEX NEW_FOLDER_NAME

Renames the flashcard folder specified by index to the new name specified.

test

This command begins a test session, where the display area enters a fullscreen.

ans ANSWER

Enter answer for a flashcard.

reveal

Immediately reveals the correct answer.

next

Presents the next lowest score flashcard in this current test session.

end

Quits the current test session or report display.

search KEYWORDS [MORE_KEYWORDS]

Searches for flashcards inside the current folder using keywords in flashcard questions.

import FILENAME

Imports a file with the specified name. Filename must include .csv extension

export FOLDER_INDEX [MORE_INDEXES]

Creates a csv file containing the flashcards from the specified folder, which can later be imported.

help

Opens the User Guide in a new window.

exit

Exits the application.