Skip to content

Latest commit

 

History

History
executable file
·
622 lines (426 loc) · 22.1 KB

UserGuide.adoc

File metadata and controls

executable file
·
622 lines (426 loc) · 22.1 KB

Know-It-All - User Guide

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 a storage solution that supports content sharing, Know-It-All is designed to help students perform rote learning more efficiently. From cramming in between lessons to focused study, the in-built 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.

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.

Information in a box like this represents additional useful information for a deeper understanding of this command.

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

3. Quick Start

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

  2. Download the latest know-it-all.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.

    Ui

  5. 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.

  6. Some commands you can try:

    • change 1 : enter the 1st flashcard folder

    • list : lists all flashcards in the current folder

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

    • delete3 : deletes the 3rd flashcard shown in the current folder

    • exit : exits the app

  7. Refer to Section 4, “Features” for details of each command.

4. Features

Command Format

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

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in addfolder FOLDER_NAME, FOLDER_NAME is a parameter which can be used as add Human Anatomy.

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

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

4.1. 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 in this section are also not valid inside a test or report session.

4.1.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]
Format (MCQ): add q/QUESTION a/ANSWER [i/INCORRECT_OPTION]…​ [h/HINT]

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

  • If multiple hints are included in the command, only the last hint will be added to the card

  • Hints are currently restricted to alphanumerical characters and spaces only

  • A card can have any number of incorrect options to denote an MCQ card

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

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

  • add q/The Hippocrates Oath states to Do no _? a/harm h/4 letters h/Rhymes with farm
    Creates a card with hint "Rhymes with farm".

4.1.2. Editing a flashcard : edit

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

Format: edit i/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.

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.

4.1.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.1.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.1.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.1.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.1.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.1.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).

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.1.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.1.10. Exit folder : change ..

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

Format: change ..

Examples:

  • change 2
    change ..
    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.2. Folder Operations

Commands listed in this section affect the application and not a single folder.

ℹ️
 The commands in this section can only be executed when you are at the home directory, outside of any folder
ℹ️
 The commands in this section are also not valid inside a test or report session.

4.2.1. 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 and non-blank. Attempting to add a folder with the same name as an existing folder 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 user can then enter the folder with the change command and begin adding cards.

4.2.2. 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.2.3. 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.

Examples:

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

4.2.4. Enter folder : change

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

Format: change FOLDER_INDEX

Examples:

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

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.5. 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]

Important
 The files used for Import and Export commands should be placed in the project root directory.
i.e The directory where the .jar file is located
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.6. 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 below
Blood.csv
Figure 1. Sample format for csv file

  • The first row of the csv file should have the following headers, Question, Answer, Options, Hints.

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

  • Options can take 0 or many values.

  • Hints can take 0 or 1 values only.

Format: import FILENAME

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.

4.3.1. Test flashcards in a folder : test

This command begins a test session, where the display area enters a fullscreen (see Figure 1 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.

  • Only questions and hints are presented and users are required to either input an attempt or enter the command to reveal the answer.

  • (MCQ cards) the ordering of options will be randomized each time the card 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 card will only be presented when the next command is carried out.

Examples:

  • test
    Starts a session by displaying a flashcard (both question and hint) from the current folder.

Hint toggle on / off feature Coming in v2.0

When extra help is needed and familiarity with the content is not yet established hints can be toggled on during a test session when a ‘-hint’ is added on at the end of the test command. Hint will be displayed along with the question when the card is presented.

Format: test [-hint]

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 enable a more engaging experience with Know-It-All, one can input an answer for the currently displayed flashcard question. Know-It-All compares the attempt with the correct answer in that card and shows if it is correct or wrong.

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

WrongAnswerPage
Figure 3. Wrong Answer page


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

CorrectAnswerPage
Figure 4. Correct Answer page


Format: ans ANSWER

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

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

  • Answer matching is case insensitive.

  • To answer MCQ cards, enter the number of 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 4
    in response to the card displayed below, where choosing option 4 will give the right answer.

AnsweringMcqCard
Figure 5. Answering an MCQ card

4.3.3. Reveal answer to a flashcard : reveal Coming in v1.4

Immediately reveals the correct answer. The user will not need attempt any answer before being presented the correct answer.

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, so there is no addition to the correct attempts of this card.

4.3.4. Go to next flashcard : next

Presents the next lowest score flashcard in this current test session. Upon a successful next command, you will see a similar page below (see Figure 4).

NextCommandPage
Figure 6. 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.

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.

Format: end

4.4. Report Operations

After testing, you can track your how you scored against previous attempts using our report feature. Because cards about a particular topic are expected to be in the same folder, the folder scores are tracked per folder.

4.4.1. Display a folder score report : report

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

ReportDisplay
Figure 7. Report display

Format: report

ℹ️
 This command is only valid inside a folder.
ℹ️
 There must be at least two test attempts for a graph to be drawn.

4.4.2. End the current report session : end

Quits the current report session.

Format: end

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, grouped topically. There are no sub-folders.

  • Test Session: A session where all flashcards in a folder are queued to have their questions displayed. The user is 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 the user is tested on a card, this number is automatically calculated and recorded.

  • Folder Score: The average of all card scores in a folder after 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]

Adds a flashcard to the current folder.

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

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 folder score report for the current folder

undo

Undoes the previous undoable command.

redo

Redoes the last undo.

change ..

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

change 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 FILENAME [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.