Table of Contents

Overview

app logo
Academy Directory (AD) is a desktop application for CS1101S tutors to manage their students. Its main features are as follows:

Academy Directory is written in Java and thus can be run on all major operating systems! It is optimized for use via a Command Line Interface (CLI), while still having the benefits of a Graphical User Interface (GUI). Academy Directory is developed as an evolution of the Address Book 3 application, primarily for usage in teaching CS1101S - Programming Methodology I - at the National University of Singapore.

Information about this User Guide

Purpose

This user guide aims to:

Target User

The current version of Academy Directory is specifically designed for CS1101S Avengers. Therefore, the main Target Audience of this user guide are CS1101S Avengers. As such, the following assumptions are made regarding the Target Audience:

  • Can type fast and are comfortable using a CLI.
  • Is comfortable downloading and installing software such as Java 11 onto their system.
  • Is familiar with the common terms relating to Computer Science.
  • Is familiar with CS1101S module structure and teaching pedagogy.

While some technical background is assumed, we also provide the definitions for certain technical terms commonly used in this user guide here. ***

Quick Start

This section provides instructions to begin using Academy Directory.

  1. Ensure you have Java 11 or above installed in your Computer. Academy Directory has been tested on Java 11 and running on other versions might result in bugs.

  2. Download the latest release here to the folder you want to use as the home folder for your Academy Directory.

  3. From the CLI, navigate to the folder used as home folder for Academy Directory and run java -jar academydirectory.jar. Ensure that the .jar file is named academydirectory.jar, otherwise the command will not work. A GUI similar to the below image should appear in a few seconds. Note how the app already contains some sample data.
    Ui

  4. Type a command in the command box and press Enter to execute it. e.g. typing help and pressing Enter will open the help window.
    Some example commands you can try:

    • list : Lists all contacts. For new users, the list will contain some sample data which users can delete.

    • visualize : Visualize grades of students. For new users, the sample grades for the assessments will be displayed in a box plot diagram.

    • exit : Exits the app.

  5. You may refer to the Features below for the set of features supported by Academy Directory and the details for each command. Alternatively, use help to get start and learn how to use our various commands. Notes:

    • While it is possible to open academydirectory.jar by double-clicking it, this may cause Academy Directory related files to be saved to an indeterminate location on the computer. As such, this method is not recommended, especially for beginners.
    • The clear command can be used to remove the sample data in Academy Directory.
    • Changes to Academy Directory are automatically saved into the database.

Preview

Have you installed Academy Directory successfully? Let us now walk you through how Academy Directory works by starting off with a tutorial on how to interpret our User Interface design.

Ui

Components of UI Functionality
Menu bar Provides an immediate mean to execute commands relating to student academic data or usage history. There are 4 menus to browse from.
Student list Shows the current list of students in your class, along with their tags and contact number. You can scroll through the list to see more students. Each student will be shown only their name, phone number (if have), email address, and tags (if have).
Command box This is where you will enter your command and press Enter to use Academy Directory Command Line Interface
Status message display This is where Academy Directory will inform you of what is happening after the commands you entered
Result visualizer display This is where Academy Directory will visualize your data or results, on your request.

Features

This section shows all the commands supported by Academy Directory.

The commands are categorized based on the main features of Academy Directory:

  • Manage students’ personal details
  • Track students’ grades, Studio attendance, and participation
  • Visualize data in Academy Directory
  • Others

For better reading experience, please be familiar with the command format (shown below) as well as some terms used.

:information_source: Notes about the command format:

  • Words in UPPER_CASE are the parameters to be supplied by the user.
    e.g. in add n/NAME, NAME is a parameter which can be used as add n/John Doe.

  • Items in square brackets are optional.
    e.g. n/NAME [t/TAG] can be used as n/John Doe t/streams or as n/John Doe.

  • 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/streams, t/envmodel t/recursion etc.

  • Parameters can be in any order.
    e.g. if the command specifies n/NAME p/PHONE_NUMBER, p/PHONE_NUMBER n/NAME is also acceptable.

  • If a parameter is expected only once in the command, but you specified it multiple times, only the last occurrence of the parameter will be taken.
    e.g. if you specify p/12341234 p/56785678, only p/56785678 will be taken.

  • Extraneous parameters for commands that do not take in parameters (such as help, list, exit and clear) will be ignored.
    e.g. if the command specifies help 123, it will be interpreted as help.

Managing students’ personal details

Adding a student: add

Adds a student to Academy Directory

Format: add n/NAME e/EMAIL te/TELE_HANDLE [p/PHONE_NUMBER]

:bulb: Tip: A student can be added without phone number.
  • PHONE_NUMBER is an optional field. The default value is NA which stands for “Not Applicable”.
  • If Avengers do not wish to enter a student’s phone number,
    • p/ prefix can be omitted from the command.
    • Otherwise, Avengers can supply the value NA to p/ prefix. Note that it must be NA not N.A or na
  • If newly inputted students have NAME matching exactly (case-sensitive) with an already existing entry, the program will output a warning message and show the existing entry.
    This student already exists in the Academy Directory.

Examples:

  • add n/Aaron Tan te/@sausage e/e0123456@u.nus.edu p/90312311
  • add n/Charles Ng te/@charles e/e0123434@u.nus.edu p/NA
  • add n/Betsy Lim te/@unislave e/e0123456@u.nus.edu

Deleting a student: delete

Deletes a student from Academy Directory by their index.

Format: delete INDEX

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

Examples:

  • delete 2 deletes the 2nd student in the currently displayed list.

Tagging a student : tag

Tags a student.

Format: tag INDEX t/TAG [t/TAG]...

  • INDEX refers to the index number shown in the displayed student list.
  • INDEX must be a positive integer 1, 2, 3, …​
  • Assigns a Tag to the student at the specified INDEX.
  • Entering the tag command with a single empty tag t/ will remove all tags assigned to the student.
  • Tags names should be alphanumeric and consist of only one word.
  • For multiple tag entries, none of the tags should be empty.
  • All existing tags will be replaced by the new tags.

Examples:

  • tag 1 t/ removes all tags from the student specified at index 1.
  • tag 1 t/mission sets mission tag to the student specified at index 1.
  • tag 2 t/streams t/envmodel sets streams and envmodel tags to the student specified at index 2.

Getting students’ personal details: get

Gets personal details of student(s). Personal detail refers to:

  • Telegram Handle
  • Email address
  • Telephone number, if any

Format: get [p/] [e/] [te/] [n/NAME]

  • At least one of the supported prefix i.e. p/, e/ or te/ must be passed in.
  • If NAME is provided, only personal detail of the student/s whose name contain the given NAME will be shown. The behavior here is similar to the filter command
  • If NAME is not provided, the personal detail of all students in Academy Directory will be shown
  • Multiple prefixes can be supplied at the same time, and personal detail corresponding to all the given prefixes will be shown
  • The order in which personal details will be shown is as follows, regardless of the order of the prefixes passed to get command:
    • Phone Number (p/)
    • Email (e/)
    • Telegram Handle (te/)

Examples:

  • get p/ shows the phone number of all students in Academy Directory
  • get p/ e/ te/ shows the phone number, email, and telegram handle of all students in Academy Directory
  • get p/ n/alex shows the phone number of all students in Academy Directory whose name has alex
  • get p/ e/ te/ n/alex show the phone number, email, and telegram handle of all students in Academy Directory whose name contains alex

Editing a student’s detail : edit

Edits a student’s personal details such as their NAME, PHONE, TELEGRAM and EMAIL.

Format: edit INDEX [n/NAME] [e/EMAIL] [te/TELE_HANDLE] [p/PHONE_NUMBER]

  • Edits the student at the specified INDEX. The index refers to the index number shown in the displayed student 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.
  • If edited NAME exactly matches (case-sensitive) with an already existing entry that is not the entry being edited, the program will output a warning message and show the existing entry.
    This student already exists in the Academy Directory.

Examples:

  • edit 1 p/91234567 e/e0425205@u.nus.edu Edits the phone number and email address of the 1st student to be 91234567 and e0425205@u.nus.edu respectively.
  • edit 2 n/Aaron Tan Edits the name of the 2nd student to be Aaron Tan.

Tracking students’ grades, Studio attendance, and participation

Adding grades for an assessment: grade

Adds a student’s grade for a particular assessment.

Format: grade INDEX as/ASSESSMENT g/GRADE

  • Record the student’s GRADE for the ASSESSMENT based on INDEX
  • Modifies the student(s) at the specified INDEX. The index refers to the index number shown in the displayed student list. The index must be a positive integer 1, 2, 3, …​
  • The input ASSESSMENT must be one of the following: RA1, MIDTERM, RA2, PE, FINAL.
  • The input GRADE must be a non-negative integer from 0 to 100 inclusive.

Example:

  • grade 1 as/RA1 g/15

Editing a student’s Studio attendance: attendance

Edits the attendance status of their students.

Format: attendance INDEX ses/STUDIO_SESSION att/ATTENDANCE_STATUS

  • Edits the attendance of a student or multiple students based on their INDEX.
  • Modifies the student(s) at the specified INDEX. The index refers to the index number shown in the displayed student list. The index must be a positive integer 1, 2, 3, …​
  • Multiple INDEX can be parsed in at once as long as they are all valid.
  • The STUDIO_SESSION field is a positive integer from 1 to 12 inclusive which refers to the Studio Session to be modified.
  • The ATTENDANCE_STATUS field can only be a 1 or 0 to indicate whether the student attended the session or not where 1 marks a student as having attended while 0 marks a student as unattended.
  • Existing values will be updated to the input values.

Examples:

  • attendance 1 ses/1 att/1 Marks the student with index number 1 as present for studio session 1
  • attendance 1, 2, 3 ses/12 att/0 Marks students with index numbers 1, 2, and 3 as absent for studio session 12
  • attendance 1, 2, 3 ses/7 att/1 Marks students with index numbers 1, 2, and 3 as present for studio session 7

Editing a student’s Studio participation: participation

Tracks the participation of their students during the relevant studios. We will be keeping track of Studio participation with a counter system which starts at 0 by default.

Format: participation INDEX ses/STUDIO_SESSION add/PARTICIPATION_TO_ADD

  • Edits the Studio participation of a student or multiple students based on their INDEX.
  • Modifies the student(s) at the specified INDEX. The index refers to the index number shown in the displayed student list. The index must be a positive integer 1, 2, 3, …​
  • The STUDIO_SESSION field is a positive integer from 1 to 12 inclusive which refers to the Studio Session to be modified.
  • The PARTICIPATION_TO_ADD field is an integer from -500 to 500 inclusive which indicates the Participation score of the student.
  • PARTICIPATION_TO_ADD will be added to the student’s current Participation score
  • A student’s Studio Participation score cannot be reduced below 0.
  • If a student’s Attendance is false and the Participation score to be added is greater than 0, the student will also be marked as having attended the Studio.

Examples:

  • participation 4 ses/9 add/1 Adds 1 to the Participation score of student with index number 4 for Studio session 9
  • participation 1, 2, 3 ses/12 add/500
  • participation 4, 6 ses/2 add/-300

Visualization Tools

Displays all information relating to a student, both personal and academic information. Information shown include the student’s name, tag, participation data, examination score, and contact information.

Format: view INDEX

  • View students’ information, both personal and academic related, based on their INDEX number on the list.
  • Information shown for the student will be in a drop-down menu listing participation and grades.
  • Contact information like phone number, email address, and Telegram handle are also displayed.

Examples:

  • view 1

View Command (after)

:bulb: Note: Avengers can also click on the student card to execute view command instead.

Displaying the grades for an assessment: show

Displays the grades and the average score of all the students for a particular assessment.

Format: show ASSESSMENT

  • Display the list of grades that the students achieved for a particular ASSESSMENT, as well as the average score.

Examples:

  • show RA1
:bulb: Note: Avengers can also browse the first menu on the top left (with the paper and pencil symbol) to execute show command instead.

Visualizing assessments’ grades of the entire class: visualize

Plots the grades and the average score of all the students for all assessments.

Format: visualize

  • Visualize assessment grades of the class with Box & Whisker plot
  • Any grade of any student that is not yet entered will not be included in the graph.
  • If there are no students found (let say after clear command), an empty plot will be shown with the feedback No students found to visualize.

visualizecommand

:bulb: Note: Avengers can also browse the second menu on the top left (with the chart symbol) to execute visualize command instead.

Filtering Academy Directory by name or tag: filter

Finds all students whose names or tags contain any of the specified keywords (case-insensitive) and displays them as a list with index numbers.

Format: filter KEYWORD [MORE_KEYWORDS]

  • The search is case-insensitive. e.g. hans will match Hans
  • The order of the keywords does not matter. e.g. Hans Bo will match Bo Hans
  • Only full words will be matched e.g. stream will not match streams
  • Students matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber, Bo Yang

Examples:

  • filter John returns john and John Doe
  • filter alex david returns Alex Yeoh, David Li
  • filter stream returns all students who are tagged with stream

Sorting student list : sort

Sorts the list of students in Academy Directory.

Format: sort attr/ATTRIBUTE ord/ORDER

  • The sort can be done on some ATTRIBUTE in either ascending order or descending order.
  • ATTRIBUTE can only be Name, Participation, RA1, Midterm, RA2, Final and Average.
  • ATTRIBUTE is case-insensitive. e.g. name and NAME will both sort the list by Name.
  • Average here refers to the average score of all Assessments.
  • Participation is sorted based on the average Participation of a Student across all Studio sessions.
  • Name is sorted lexicographically.
  • ORDER can only be asc and desc which indicate either ascending or descending sort.
  • ORDER is case-insensitive. e.g. ASC and Asc will both sort the list in ascending order
  • Both ATTRIBUTE and ORDER are required for the sorting to work.

Examples:

  • sort attr/RA1 ord/desc sorts the list in descending order based on their RA1 grades.
  • sort attr/participation ord/asc sorts the list in ascending order based on their participation score.

Others

Listing all students : list

Shows a list of all students in Academy Directory.

Format: list

  • This command is very useful to escape from the focused list obtain after running certain commands such as filter

Clearing all students : clear

Clears all students from Academy Directory. This will result in an empty Academy Directory

Format: clear

Undo changes to Academy Directory: undo

Undo changes made to Academy Directory data.

Format: undo

  • undo only reverts changes made
  • undo will display an error message if there are no changes to be undone
  • To see the list of commands that can be undone using undo, read here

Example:

  1. clear command executed to clear the Academy Directory

undoCommandBefore

  1. undo command executed to obtain the original Academy Directory

undoCommandAfter

:bulb: Note: Avengers can also browse the third menu on the top left (with the clock symbol) to execute undo command instead.

Redo changes to Academy Directory: redo

Redo the changes made to Academy Directory data that were undone using the undo command.

Format: redo

  • redo only reverts changes made
  • redo will display an error message if there are no changes to be redone
  • To see the list of commands that can be redone using redo, read here

Example:

  1. undo command executed after a clear command to obtain the original Academy Directory

undoCommandAfter

  1. redo command executed to redo the changes and clear the Academy Directory.

redoCommand

:bulb: Note: Avengers can also browse the third menu on the top left (with the clock symbol) to execute redo command instead.

Seeking help : help

help message

Provides in-depth assistance using Academy Directory with help command, either generally or specifically.

Viewing general help

Format: help

  • Typing in help singularly will display a menu of all commands available to use as a list, how to navigate each command, alongside the syntax for each command.
Viewing specific help

Format: help COMMAND_NAME

  • Displays all information related to the command, which includes
    • What the command is about.
    • Why the command is needed.
    • What the syntax for the command is.
    • Example of usage and expected results.

Note that help help will result in a general help window. We do not provide instruction for the command help itself.

Examples:

  • help
  • help add: Displays the exact same content as what is shown on this User Guide for the add command
:bulb: Note: Avengers can also browse the fourth menu on the top left (with the question symbol) to execute a general help command instead.

Exiting the program : exit

Exits the program.

Format: exit

Alternatively, users can exit by clicking the X button on the top right corner of the application window.

[For Advanced Users] Viewing Commit History: history

Shows local commit history.

Format: history

  • Only commands that result in a state change in Academy Directory will be committed. Such commands include add, edit, delete, clear, and more. For a full list, refer to the appendix.
  • Commits are sorted based on time, with the most recent commit shown at the top and the initial commit shown at the bottom
  • The commit corresponding to current Academy Directory state is labelled with “(HEAD)”
  • The commit corresponding to current branch is labelled with “(MAIN)”
  • The commit corresponding to old branch is labelled with “(OLD)”
  • Old branch is shown at the left, current branch at the right
  • The corresponding commit hash is the five character string displayed
  • Note that current implementation of history command can only show 2 branches: “OLD” and “MAIN”. If there are already two branches and a third branch is going to be made, then the oldest branch will not be visible.

The following image shows the output of history. Note that some commits are labelled. The label “(HEAD)” is used to indicate current state. historyCommand1

:bulb: Note: Avengers can also browse the third menu on the top left (with the clock symbol) to execute history command instead

[For Advanced Users] Reverting Commit: revert

Reverts state of Academy Directory to a previous commit.

Format: revert HASH

  • HASH refers to the commit hash of the commit to be reverted to
  • HASH can be obtained using the history command
  • Error message will be shown if attempting to revert to the current commit. This is because reverting to current commit is unlikely to be intentional.

The following image shows the output of history. The commit hashes are labelled. We can pick which commit to revert to, and then type revert <CORRESPONDING_HASH> to revert to that commit. historyCommand

Example:

  • revert ee5e5 reverts state of Academy Directory to the commit with hash starting with ee5e5

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 Academy Directory home folder. Overwrite the version control folder it creates with the version control folder of your previous Academy Directory to retain commit history.

:exclamation: Caution: Invalid changes to any of the version control files may result in undefined behavior as this is not an intended use case. Proceed at your own risk.

Q: How do I save my data?
A: Academy Directory data are saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

Q: Can I edit the data file?
A: Academy Directory data are saved as a JSON file [JAR file location]/data/academydirectory.json. Advanced users are welcome to update data directly by editing that data file.

:exclamation: Caution: If your changes to the data file makes its format invalid, Academy Directory will discard all data and start with an empty data file at the next run.

Q: How do I commit changes made to Academy Directory?
A: Academy Directory implements an internal version control system (VCS) to keep track of state changes. Unlike some VCS, however, the internal VCS in Academy Directory will automatically stage and commit changes made to Academy Directory, including commit message. Only commands that change the Academy Directory data will be staged and committed.

Q: Can I edit the version control files?
A: Version control related files are saved as text files at [JAR file location]/data/vc/. Advanced users are welcome to look at the files in this folder.

Q: When I run Academy Directory via Command Prompt, a warning message appears that there are unsupported JavaFX configurations. Do I need to be concerned about this?
A: No, both usability and functionality wise. Academy Directory was not developed as a modular-based application, however, some features of our app do implement external modules not declared, and thus is the warning message. The problem has been addressed while our application was developed, but we have decided to left the warning as it is as addressing the warning is outside the scope of CS2103T and our project requirement itself.

Q: Why is Telegram a compulsory field and not shown on the student card, yet phone number is optional and is shown on the student card?
A: There are many internal considerations when we design this. Initially, we have planned to put all 3 fields into the student card. However, due to some privacy concerns regarding the Telegram handles, as well as the fact that it does not look nice on the card, we decided to remove Telegram out of the card and leave it only for view. We may add Telegram again in the future iterations depending on the future.

Summary

This section provides a summary of commands and prefixes in Academy Directory.

Command Summary

This subsection provides a summary for all the commands used in Academy Directory.

Action Format Examples
Add Student add n/NAME e/EMAIL te/TELE_HANDLE [p/PHONE_NUMBER] [t/TAG] add n/James Ho te/@TeleHandle p/22224444 e/jamesho@example.com t/Streams
Delete Student delete INDEX delete 3
Tag Student tag INDEX t/TAG [t/TAG]... tag 1 t/mission t/streams
Get Personal Detail get [p/] [e/] [te/] [n/NAME] get p/ e/ te/ n/Alex Yeoh
Edit Personal Detail edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [te/TELE_HANDLE] edit 2 n/James Lee e/jameslee@example.com
Add Grade grade INDEX as/ASSESSMENT g/GRADE grade 1 as/RA1 g/15
Edit Attendance attendance INDEX ses/STUDIO_SESSION att/ATTENDANCE_STATUS attendance 1, 2 ses/1 att/1
Edit Participation participation INDEX ses/STUDIO_SESSION add/PARTICIPATION_TO_ADD participation 1 ses/12 att/0
Show Grades show ASSESSMENT show RA1
Visualize all grades visualize visualize
Filter Academy Directory filter KEYWORD [MORE_KEYWORDS] filter James Jake
Sort Student List sort attr/ATTRIBUTE ord/ORDER sort attr/average ord/asc
List All Students list list
Clear Student List clear clear
Undo undo undo
Redo redo redo
Help help [COMMAND_NAME] help add
Exit exit exit
View Commit History history history
Revert Commit revert HASH revert df7x3

Prefix Summary

This subsection provides a summary for all the fields and their prefixes used in Academy Directory. Note that not all fields have a prefix; such fields will have N.A. be written in their Prefix column.

Field Prefix
INDEX N.A.
COMMAND_NAME N.A.
NAME n/
EMAIL e/
TELE_HANDLE te/
PHONE_NUMBER p/
TAG t/
STUDIO_SESSION ses/
ATTENDANCE_STATUS att/
PARTICIPATION_TO_ADD add/
ASSESSMENT as/
GRADE g/
ATTRIBUTE attr/
ORDER ord/
HASH N.A

Glossary

This section explains the commonly used terms in this user guide.

Term Definition Comments
CS1101S An introductory Computer Science module for year 1 students in the the National University of Singapore.  
Studios Tutorials held in CS1101S and are essential in aiding the students to improve their grasp on the concepts taught during the lecture.  
Avengers A special term to call a CS1101S tutor. An avenger organizes a Studio session to improve on CS1101S concepts taught in lecture, recording attendance and grades.  
Command Line Interface (CLI) A text-based user interface, where users type commands to instruct the computer to do something.  
Graphical User Interface (GUI) A graphics-based user interface, where users click buttons to instruct the computer to do something.  
Java A program that allows running other programs written in Java programming language.  
Operating System Software that manages computer hardware and other computer software.  
Command An instruction typed by a user to Academy Directory.  
Command Box A part of the Academy Directory’s GUI which can be used by users to type commands.  
Field Additional information that can be provided to a command for correct command execution. May or may not have an associated prefix
Parameter Part of the command which provides additional information provided by the user. Actual values for the fields
Prefix An abbreviation of a field. Always ends with a backslash (‘/’)
Lexicographically Refers to the generalization of the alphabetical order of the dictionaries to sequences of ordered symbols or, more generally, of elements of a totally ordered set. More information can be found here.  
Singular command Refers to commands with only one keyword If there are any other arguments after the command, then an error message will be shown

Appendix

Appendix A: Version Controlled Commands

The following list is a list of commands that are version controlled i.e. they can be undone and redone using the undo command and the redo command. Furthermore, the use of these commands will be reflected in the commit history, using the history command.

Commands not shown in the above list will not appear in the commit history, and thus cannot be reverted to and / or be undone or redone.

Academy Directory Resources

  • Developer Guide: If you’re interested in developing Academy Directory further, or only wish to see the gory details
  • About Us: If you’re interested to learn more about us
  • Github: If you want to see our code or report any issues

Other Resources

Acknowledgements