Skip to content

UserGuide.adoc

Latest commit

 

History

History
530 lines (348 loc) · 18 KB

UserGuide.adoc

File metadata and controls

530 lines (348 loc) · 18 KB
Raw

CardiB - User Guide

By: Team T10-2 Since: Jan 2020 Licence: MIT

1. Introduction

Cardi Buddy (CardiB) is for students who prefer to use a desktop app to store their revision materials as flashcards. More importantly, CardiB is optimized for those who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, CardiB can help you to store revision materials quickly. The self-testing features will definitely help you to ace your examinations as opposed to traditional ways of revision by re-reading lecture notes. Interested? Jump to Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

  1. Ensure you have Java 11 or above installed in your Computer.

  2. Download the latest cardibuddy.jar here.

  3. Copy the file to the folder you want to use as the home folder for your Cardi Buddy.

  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 example commands you can try:

    • list : lists all decks

    • addd/CS1101S t/Basics : adds an empty deck titled CS1101S to the Cardi Buddy.

    • open 1 : opens the 1st deck shown in the current list

    • delete deck3 : deletes the 3rd deck shown in the current list

    • exit : exits the app

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

3. Features

Application-specific Terminologies

  • Decks are the containers that contain the flashcard. A flashcard can only exist in a deck.

  • Flashcards are cards that contain revision materials, specifically a question and an answer.

  • Statistics is the numererical, summarized version of your data, based on your test history. Your statistics can serve as a guideline for you to decide which areas you need to work on, and which areas you are familiar with.

Common Terminologies

  • File path specifies the unique location of a file in a file system from the root directory.

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in add d/TITLE, TITLE is a parameter which can be used as add d/CS1101S.

  • Items in square brackets are optional e.g d/TITLE [t/TAG] can be used as d/CS1101S t/Basics or as d/CS1101S.

  • Items with …​ after them can be used multiple times including zero times e.g. [t/TAG]…​ can be used as   (i.e. 0 times), t/Easy, t/Easy t/Basics etc.

  • Parameters can be in any order e.g. if the command specifies d/TITLE t/TAG, t/TAG d/TITLE is also acceptable.

Special Icons

  • 💡 is used to signal information that is helpful for the users to know.

3.1. Basic Features

3.1.1. Viewing help : help

Lists all the available commands that a user can enter.
Format: help

3.1.2. Saving data

The data is automatically saved into the hard disk after the user enters any command that changes the data

There is no need to save manually.

3.1.3. Exiting program: exit

Exits the program. Format: exit

3.2. Opening

3.2.1. Opening a deck: open

Opens an existing deck in the library. Format: open INDEX

Shows a list of all the cards in the deck.
Format: open 1

3.3. Adding

3.3.1. Adding a deck: add d/TITLE

Creates a new deck to be added to the library. Format: add d/TITLE [t/TAG]…

  • Tag names are alphanumeric with no spaces E.g. t/Core Module is an invalid tag while t/CoreModule is valid.

Examples:

  • add d/CS2103
    Returns a new deck titled CS2103

  • add d/CS1101S t/Easy t/Basics
    Adds a new deck titled CS1101S with the tags Easy and Basics

3.3.2. Adding a normal card: add c/DECK_INDEX q/QUESTION a/ANSWER

Creates a new card to be added to the deck. Format: add c/DECK_INDEX q/QUESTION a/ANSWER

  • The deck specified in DECK_INDEX must be open for you to add a card.

Examples:

  • open 2
    add c/2 q/How does one go about solving recursion problems? a/Wishful thinking
    Adds a new card belonging to the deck indexed at 2.

AddCard

3.3.3. Adding an image card: add p/file:FILE_PATH_TO_IMAGE c/DECK_INDEX q/QUESTION a/ANSWER

Creates a new image card to be added to the deck. Format: add p/file:FILE_PATH_TO_IMAGE c/DECK_INDEX q/QUESTION a/ANSWER

  • The deck specified in DECK_INDEX must be open for you to add a card.

  • The images can only be PNG or JPG files.

  • The FILE_PATH_TO_IMAGE must end with .png or .jpg suffix.

Examples:

  • open 1
    add p/file:/Users/qiujingying/Documents/GitHub/cs2103/main/docs/images/ArchitectureDiagram.png c/1 q/What type of diagram is this? a/Architecture Diagram
    Adds a new card with an image belonging to the deck indexed at 1.

AddImageCard
💡
 You can drag and drop the image you want to add into a terminal window to obtain its file path. File paths may differ across operating systems (Windows vs Mac).

3.3.4. Adding an image card via the Image button: c/DECK_INDEX q/QUESTION a/ANSWER

Shortcut for users who do not want to search for the file path.

3.4. Opening

3.4.1. Opening a deck: open

Opens an existing deck in the library. Format: open DECK_INDEX

Shows a list of all the cards in the deck.
Format: open 1

3.5. Editing

3.5.1. Editing a deck: edit

Edits an existing deck in the library. Format: edit DECK_INDEX [d/TITLE] [t/TAG]…

  • Edits the decks at the specified DECK_INDEX. The index refers to the index number shown in the complete list of decks. 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.

  • When editing tags, the existing tags of the deck will be removed i.e adding of tags is not cumulative.

  • You can remove all the deck’s tags by typing t/ without specifying any tags after it. If not, the tags will not be removed.

Examples:

  • edit 1 d/CS2103T
    Edits the title of the 1st deck to be CS2103T without removing existing tags.

  • edit 2 d/CS2040 t/
    Edits the title of the 2nd deck to be CS2040 and clears all existing tags.

3.5.2. Editing a card: edit card [coming in v2.0]

Edits an existing card in the deck. Format: edit card CARD_INDEX [q/QUESTION] [a/ANSWER] [t/TAG]…

  • You must open a deck before you can edit a flashcard. A flashcard can only exist inside a deck.

  • Edits the card at the specified CARD_INDEX. The index refers to the index number shown in the complete list of decks. 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.

  • When editing tags, the existing tags of the card will be removed i.e adding of tags is not cumulative.

  • You can remove all the card’s tags by typing t/ without specifying any tags after it.

Examples:

  • open 1
    edit card 1 q/What does MVC stand for?
    Opens the first deck and tEdits the question of the 1st card to be What does MVC stand for?.

  • open 1
    edit card 2 a/cs2040 t/
    Edits the answer of the 2nd card to be cs2040 and clears all existing tags.

3.6. Listing

3.6.1. Listing all decks: list

Shows a list of all the decks in the library and hides the displayed cards (if any).
Format: list

3.7. Clearing

3.7.1. Clearing all decks: clear

Clears all deck entries from the library.
Format: clear

3.8. Deleting

3.8.1. Deleting a deck: delete deck

Deletes the specified deck from the library. Format: delete deck DECK_INDEX

  • Deletes the deck at the specified DECK_INDEX.

  • The index refers to the index number shown in the complete list of decks.

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

Examples:

  • list decks
    delete deck 2
    Deletes the 2nd deck in the library.

  • search deck cs2030
    delete deck 1
    Deletes the 1st deck in the results of the search command.

3.8.2. Deleting a card: delete card

Deletes the specified card from a specific deck. Format: delete INDEX d/DECK_TITLE

  • You must open a deck before you can delete a flashcard. A flashcard can only exist inside a deck.

  • Deletes the card at the specified INDEX of the deck.

  • The index refers to the index number shown in the complete list of flashcards in the deck.

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

Examples:

  • open 1
    delete card 2 d/cs2030
    Opens the first deck and deletes the 2nd flash card in the deck.

  • search card java
    delete card 1
    Deletes the 1st card in the results of the search card command.

3.9. Searching

3.9.1. Searching for a deck: search deck

Searches for the decks with titles that contain any of the given keywords or all of the keywords concatenated with the & symbol. Format: search deck KEYWORD [&] [MORE_KEYWORDS]

  • If the search has a & symbol, only decks with the words concatenated before and after the symbol will be returned.

  • The search is case insensitive. e.g cs2040 will match CS2040

  • The order of the keywords does not matter. e.g. Science Module will match Module Science

  • Only titles of the decks are searched.

  • The keyword needs to match a word within the deck’s title exactly . e.g. cs will not match with cs2030

Examples:

  • search deck database
    Displays decks with the word database in the titles.

  • search deck database & relational
    Displays decks with both of the words database and relational in the titles.

3.9.2. Searching for a card: search card

Finds the cards with a question that contain any of the given keywords. Format: search card KEYWORD [&] [MORE_KEYWORDS]

  • A deck needs to be opened for the search card command to work. The command will only search for cards in the opened deck.

  • If the search has a & symbol, only cards with the words concatenated before and after the symbol, in the question, will be returned.

  • The search is case insensitive. e.g programming will match Programming.

  • The order of the keywords does not matter. e.g. Javascript programming language will match with programming language Javascript.

  • The keyword needs to match a word within the question exactly. e.g. Java will not match with Javascript.

Examples:

  • search card principle
    Displays cards with the word principle in the questions.

  • search card diagram & UML
    Displays decks with both of the words diagram and UML in the questions.

3.10. Filtering

3.10.1. Filtering by tags: filter

Filters across all decks and only displays the decks with the specific tag. Format: filter TAGNAME [&] [MORE_TAGNAMES]

  • If the search has a & symbol, only decks with the tags concatenated before and after the symbol will be returned.

  • Filtering by tag is case insensitive. e.g hard will match Hard

Examples:

  • filter hard
    Displays decks with the tag hard.

  • filter hard & coremodule
    Displays decks with both the tags hard and coremodule. <<<<<<< HEAD

3.11. Testing

Of course, you did not create all those decks and flashcards just so you can admire them! It’s time to get your revision on. Start a test session for a deck to begin testing yourself!

A test session works just like how flashcard testing works in real life - You look at the question, think of the answer, and 'flip' the card around to see if your answer matches the one on the flashcard.

The difference here is that you do not need to manually keep track of how many flashcards you got right and wrong — CardiBuddy does all that for you!

3.11.1. Retesting

A test session in CardiBuddy is special - it includes a retesting feature to make sure you know your content well.

When you answer a flashcard’s question wrongly, you will encounter it again later on in the same test session. There is no need to do this manually - CardiBuddy does this for you too.

Hence if you keep getting a question wrong, a test session can go on and on forever - unless you finally get it right, or you quit the test session!

3.11.2. Starting a test session for a deck: test INDEX

To start your test session, replace INDEX with the index number of the deck you wish to test. This number will be to the left of the title of your deck, when you are viewing all your decks as a list.

What this command does:

  • A test session will immediately replace the normal deck and flashcard list view.

  • The first question of the test session will be displayed.

Example Usage:

  • test 1
    Creates a test session for the 1st deck.

3.11.3. To answer the question: ans YOUR_ANSWER

Replace YOUR ANSWER with your answer to the displayed question.

What this command does:

  • Submits your answer, and checks your answer against the flashcard’s stored answer

  • Displays the result of your answer (CORRECT or WRONG)

  • Displays your answer and the flashcard’s answer

Example Usage:

  • ans CardiBuddy
    To answer the question: "What is the name of this application?"

3.11.4. Don’t want to answer? Skip a question with: skip

What this command does:

  • If you already know the answer to the question, and don’t want to waste your time answering it, just type skip to go to the next question.

  • Your skipped flashcard will not impact your overall test score, and CardiBuddy will merely remove it from your current test session.

Note:

  • You can use this command if either:

    • You have not answered the question.

    • You have answered the question, but you got it wrong.

  • CardiBuddy will not let you use skip if you have already gotten that question correct.

3.11.5. To force your wrong answer to be marked as correct: force

What this command does:

  • CardiBuddy’s uses automated marking to mark your answers. It takes your answer word for word when checking against the model answer stored in your flashcard.

  • If your answer differs from the model answer, it will be marked as wrong.

  • After submitting your answer, you will get to see the model answer and your answer, for you to compare them.

  • If you feel that your answer still meets the question’s requirements, you can force your answer to be marked as correct.

3.11.6. To go to the next question: next

What this command does:

  • After submitting your answer, type next to go to the next question (if there are any left to test).

Note:

  • You can only type next once you have submitted your answer.

3.11.7. Quit the test session halfway: quit

What this command does:

  • Allows you to quit the current test session even before it is completed.

3.12. Displaying History

3.12.1. Displaying the command history: 'history'

Displays all the commands that has been inputted by the user during the current session. Format: 'history'

3.13. Undo/Redo

3.13.1. Undoing command: undo

Undoes latest command. Format: undo

3.13.2. Redoing command: redo

Redoes latest command. Format: redo

3.14. Detecting duplicates

3.14.1. Detecting duplicate deck

Upon adding a new deck, the application automatically checks if there are any existing decks with the same title. Only decks with unique titles can be successfully added.

3.14.2. Detecting duplicate card

Upon adding a new card to a specific deck, the application automatically checks if there are any existing cards with the same question in that deck. Only cards with unique questions can be successfully added.

If there is a card with the same question but it is in a different deck, the card can still be successfully added.

3.15. Statistics

  • Shows the number of Decks/Cards created and deleted, number of Test Sessions played, average correct percentage, average number of tries for each question.

  • Includes a line graph of the history of test previous test results.

3.15.1. Displaying all statistics: statistics

Displays the statistics across all decks. Format: statistics

3.15.2. Displaying statistics of a certain Deck: statistics

Displays the statistics of a specific deck. Format: statistics INDEX

Example:

  • statistics 2
    Shows the statistics of the deck with the shown index of 2.

3.15.3. Displaying statistics of a test session of a certain Deck: statistics

Displays the statistics of a test session of a specific deck. Format: statistics INDEX TEST_SESSION_INDEX

Example:

  • statistics 2 3
    Shows the statistics of the 3rd test session of the deck with the shown index of 2.

3.16. Syncing across multiple platforms: sync [coming in v2.0]

3.17. Playing memory games: game [coming in v2.0]

3.18. Customising flashcards UI: custom [coming in v2.0]

3.19. Replacing image [coming in v2.0]

4. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous Cardi Buddy folder.

5. Command Summary

  • Add deck : add d/TITLE [t/TAG]…​
    e.g. add d/CS2030 t/Fundamentals t/Medium

  • Add normal card : add c/DECK_INDEX q/QUESTION a/ANSWER
    e.g. add c/1 q/What does OOP stand for? a/Object Oriented Programming

  • Add image card : add p/file:FILE_PATH_TO_IMAGE c/DECK_INDEX q/QUESTION a/ANSWER
    e.g. add p/file:/Users/foo/ObjectDiagram.png c/1 q/Which SOLID principle did the code not adhere to? a/Single Responsibility Principle

  • Clear : clear

  • Delete deck/card : delete deck/card INDEX
    e.g. delete deck 3

  • Edit : edit INDEX [d/TITLE] [t/TAG]…​
    e.g. edit 2 d/CS2103T t/

  • Exit : exit

  • Force : force

  • Filter : filter TAGNAME [&] [MORE_TAGNAMES]
    e.g. filter hard & CS

  • History : history

  • Next : next

  • List : list

  • Next : next

  • Open : open INDEX
    e.g. open 2

  • Quit : quit

  • Search deck/card : search deck/card KEYWORD [&] [MORE_KEYWORDS]
    e.g. search database & relational

  • Statistics deck/card : search deck/card KEYWORD [&] [MORE_KEYWORDS]
    e.g. search database & relational

  • Redo : redo

  • Statistics : statistics

  • Test : test INDEX
    e.g. test 1

  • Undo : undo