Welcome to TeachStack!

At TeachStack, our mission is simple: to ensure every computer science instructor is able to provide the support their students need. As enrollment in computer science courses continues to rise, the demand for effective teaching tools has never been greater. Designed specifically for Command Line Interface (CLI) users like you, TeachStack is an intuitive and customizable application that empowers instructors to actively manage their students through group-building features, archiving, and strength categorization.

Join us on this journey of educational excellence with TeachStack. With TeachStack, let’s empower instructors and elevate the standard of computer science education.

Happy teaching!

Table of contents

• TeachStack
• Table of Contents
• 1. Welcome
• 2. How to use this user guide
  • 2.1 Terminologies and Symbols
• 3. Target User
  • 3.1 Assumptions
• 4. Purpose of User Guide (UG)
• 5. Quick Start
• 6. Understanding our graphical user interface
• 7. Features
  • 7.1 Viewing Help
  • 7.2 Adding a student
  • 7.3 Listing all students
  • 7.4 Editing a student
  • 7.5 Viewing a student
  • 7.6 Deleting a student
  • 7.7 Forming focus groups
    • 7.7.1 Forming focus groups manually
    • 7.7.2 Forming focus groups randomly
  • 7.8 Filtering students by groups
  • 7.9 Clearing all entries
  • 7.10 Archiving Features
    • 7.10.1 Archiving a student
    • 7.10.2 Editing an archived student
    • 7.10.3 Deleting an archived student
    • 7.10.4 Unarchiving a student
    • 7.10.5 Clearing all entries
  • 7.11 Exiting the program
  • 7.12 Saving data
  • 7.13 Editing the data file
  • 7.14 Setting a weak threshold
  • 7.15 Viewing summary statistics
• 8. Glossary
• 9. FAQ
  • 9.1 General concerns
  • 9.2 Using TeachStack
• 10. Known Issues
• 11. Command Summary

1. Welcome!

Thank you for choosing to use TeachStack! Our product aims to help you allocate resources to keep track of weaker students, and is optimized to be used with the Command Line Interface (CLI).

This is achieved through the use of focus groups, which are groups consisting of students of a weaker skill level. Focus groups can then be assigned teaching resources such as consultation slots, instructors, teaching venues, and more. By teaching students of a similar skill level together (i.e. ability grouping), you can tailor your teaching to fit a specific student demographic instead of a one-size-fits-all approach, saving you time and effort. Not to mention, ability grouping is proven to improve the group’s progress as a whole. So, are you ready to help students in need?

2. How to use the user guide

This guide explains how you can use TeachStack to manage weaker students. It will walk you through each feature and functionality of the app, ensuring you’re equipped to make the most of TeachStack’s capabilities.

• To get started with TeachStack. Quick start
• To understand the GUI. Understanding our GUI
• To see details of the commands and features. Features
• To quickly navigate to a specific section. Table of contents
• To see an overview of all commands. Command summary
• If you encounter any technical term, please refer to the glossary. Glossary
• If you encounter any problem, you may find your answer in the FAQ. FAQ

2.1 Terminologies / Symbols

Extra information are given in boxes:

• denotes additional information

• denotes warning that can cause error

The explanation of each command will be formatted in the following convention:

1. What the command does
2. The format of the command
3. Valid values that the command can take in
4. Example usages
5. Optional Screenshot

3. Target user/audience

TeachStack is tailored for computer science instructors, currently only for those in NUS. This is due to our constraints on email, studentID, grading scheme format.

3.1 Assumptions

1. We assume that users are passionate educators who wish to see their students succeed. This is important as TeachStack mainly allows instructors to track the performance of weaker students, so the application can only demonstrate its full potential in the hands of instructors who care.
2. We also assume that users are somewhat familiar with computers and have used computer applications in the past, which will help them follow this guide and use TeachStack effectively. Since most instructors will have used similar applications (e.g. Canvas), this is a reasonable assumption to make.

4. Purpose of User Guide (UG)

The purpose of the User Guide (UG) for TeachStack is to provide users with a comprehensive understanding of the application’s features and functionalities. Structured to facilitate ease of use and enhance productivity, the guide offers clear instructions, detailed explanations, and reference materials such as command summaries and a glossary. By empowering users with the knowledge to efficiently navigate TeachStack’s Command Line Interface (CLI) and Graphical User Interface (GUI), the UG aims to streamline student management tasks and ensure optimal utilization of the application’s capabilities.

5. Quick start

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

2. Download the latest TeachStack.jar from here.

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

4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar TeachStack.jar command to run the application.
   A GUI similar to the below should appear in a few seconds. Note how the app contains some sample data.
   

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

   • list : Lists all students.
   • add id/A0123459H n/John Doe e/e0123456@u.nus.edu g/B : Adds a student named John Doe to the list.
   • delete A0123459H : Deletes the student with student id A0123459H from the list.
   • clear : Deletes all students.
   • exit : Exits the app.

6. Refer to the Features below for details of each command.

6. Understanding our GUI

1. Menu Bar: Provides a selection of menu items:
   • File
     • Exit: Allows you to close the application.
   • Help
     • Help: Shows a message on how to access the help page.
   • Theme
     • Dark: Switches the application theme to a dark mode for better visibility in dark environments.
     • Light: Switches the application theme to a light mode for better visibility in bright environments. Theme is set to light mode by default.
2. Command Box: Type in commands to be executed here.
3. Result Display Box: Displays commands’ results and any errors.
4. List Selection Bar: Provides a selection of student lists to view:
   • Persons: Displays active student list.
   • Archived: Displays archived student list.
5. Student List: Lists students and their details.
6. Weak marker: Indicates a weaker student.
7. Group labels: Indicates the groups in which a student belongs to.

7. Features

7.1 Viewing help : help

Shows a message explaining how to access the help page.

Don’t worry about saving this user guide, as this link will lead you back here!

Format: help

7.2 Adding a student : add

Adds student details to the persons list. Specifying a group is optional.

Format: add id/STUDENT_ID n/NAME e/EMAIL g/GRADE [gp/GROUP_NAME]​...

• NAME, STUDENT_ID, GRADE, and EMAIL must be specified. GROUP_NAME is optional.
• NAME is case-sensitive.
  • e.g. John Doe is different from john doe
• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• EMAIL should be of the format username@domain. The username should start with e, followed by 7 digits. The domain should be u.nus.edu.
  • e.g. e0123456@u.nus.edu
• GRADE should be one of the valid grades: [A+, A, A-, B+, B, B-, C+, C, D+, D, F].
• GROUP_NAME must only contain alphanumeric characters and space, if you choose to specify a group.

Example:

• add id/A0123459X n/John Doe e/e0123456@u.nus.edu g/A adds the student named John Doe with STUDENT_ID “A0123459X”, EMAIL “e0123456@u.nus.edu” and GRADE “A” to the list.

Expected output:

7.3 Listing all students : list

Shows a list of all students, ordered by grades in descending order, i.e. [F, D, D+, C, C+, B-, B, B+, A- A, A+].

Format: list

• Displays student’s email that is a clickable link to open the user’s mailbox with a new email to the student’s email address.

7.4 Editing a student : edit

Edits an existing student (as specified by STUDENT_ID) in the list of students. Existing fields are updated to match the specified input fields.

Format: edit STUDENT_ID [id/STUDENT_ID] [n/NAME] [e/EMAIL] [g/GRADE] [gp/GROUP_NAME]...

• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• NAME is case-sensitive.
  • e.g. John Doe is different from john doe
• EMAIL should be of the format username@domain. The username should start with e, followed by 7 digits. The domain should be u.nus.edu.
  • e.g. e0123456@u.nus.edu
• GRADE should be one of the valid grades: [A+, A, A-, B+, B, B-, C+, C, D+, D, F].
• The student with the specified STUDENT_ID must exist in the list.
• Editing GROUP will overwrite existing GROUP entries.
• Use of GROUP prefix gp/ in an edit command without specifying GROUP_NAME will clear all existing GROUP of the student.
• This command will not apply to a student who is archived. In order to edit an archived student, look at the edit_archived command.

Examples:

• edit A0123459X e/e0123450@u.nus.edu Edits the email address of the student with STUDENT_ID = A0123459X to be e0123450@u.nus.edu.
• edit A0123459X n/John Doe Edits the name of the student with STUDENT_ID = A0123459X to be John Doe.

Expected output:

7.5 Viewing students : view

Shows the detailed information of the student with the specified STUDENT_ID.

Format: view STUDENT_ID

• Returns the detailed information of the student with the corresponding STUDENT_ID.
• The STUDENT_ID is case-sensitive.
• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• This feature is not applicable to the archived list, i.e. you can only view current students.

Examples:

• view A0123459X Shows the detailed information of the student with STUDENT_ID = A0123459X

7.6 Deleting a student : delete

Deletes the specified student from the list.

Format: delete STUDENT_ID

• Deletes the student with the specified STUDENT_ID.
• The STUDENT_ID refers to the id corresponding to the student in the list.
• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• The student with the specified STUDENT_ID must exist in the list.
• This command will not apply to a student who is archived. In order to delete an archived student, look at the delete_archived command.

Examples:

• delete A0123459X deletes the student with STUDENT_ID = A0123459X from the list.

Expected output:

7.7 Forming focus groups

7.7.1 Forming focus groups manually : group

Creates a group with students corresponding to the selected IDs.

Format: group gp/GROUP_NAME… id/STUDENT_ID…

• The group name includes students with the corresponding STUDENT_IDs.
• If any of the given STUDENT_IDs do not exist, the command completely fails.
• GROUP_NAME cannot be empty, and must only contain alphanumeric characters and space.
• Giving no parameter for GROUP_NAME will clear the given students’ current groups!

Examples:

• group gp/3 id/A0123456X id/A0123456H forms a group called 3 with 2 students in it.
• group id/A0123456X id/A0123456H removes the corresponding 2 students from any groups they are currently in.

7.7.2 Forming random groups : random

Puts all students marked as weak into the specified number of groups.

Format: random NUMBER_OF_GROUPS gp/GROUP_NAME

• Form groups NUMBER_OF_GROUPS with the specified GROUP_NAME followed by numbering.
• The NUMBER_OF_GROUPS refers to the number of groups to distribute students into.
• NUMBER_OF_GROUPS must be a positive integer that is smaller than the number of students marked as weak.
• GROUP_NAME cannot be empty, and must only contain alphanumeric characters and space.

Examples:

• random 3 gp/Random Group randomly distributes all weaker students into 3 groups: Random Group 1, Random Group 2, Random Group 3.

7.8 Filtering students by groups : find

Updates the list to display only students that are in the group(s) specified.

Format: find gp/GROUP_NAME…

• At least one GROUP_NAME must be specified. Otherwise, the command will fail.
• If multiple GROUP_NAMEs are specified, only students who are in all groups entered will be displayed.
• GROUP_NAME cannot be empty, and must only contain alphanumeric characters and space.
• Only the persons list will be updated, archived list will not be updated.
• Result displayed refers to the number of students found in the persons list.

Examples:

• find gp/Group 1 will update the list to display all students assigned to Group 1.
• find gp/Group 1 gp/Group 2 will update the list to display all students assigned to both Group 1 and Group 2.

7.9 Clearing all entries : clear

Clears all entries from the list of students.

Format: clear

7.10 Archiving Features

7.10.1 Archiving a student : archive

Archives a student from the persons list. That student is moved to the archived list.

Format: archive STUDENT_ID

• Archives a student with the specified STUDENT_ID.
• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• The student with the specified STUDENT_ID must exist in the persons list.

Example:

• archive A0123459X archives a student with student_id = A0123459X.

Expected output:

7.10.2 Editing an archived student : edit_archived

Edits details of an archived student.

Format: edit_archived STUDENT_ID [id/STUDENT_ID] [n/NAME] [e/EMAIL] [g/GRADE] [gp/GROUP_NAME]...

• Edits the details of an archived student with the specified STUDENT_ID.
• At least one of the optional fields indicated within the square bracket must be provided.
• The ... after the GROUP_NAME indicates that multiple GROUP_NAMEs can be provided for editing.
• The student with the specified STUDENT_ID must exist in the archived list.
• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• EMAIL should be of the format username@domain. The username should start with e, followed by 7 digits. The domain should be u.nus.edu.
  • e.g. e0123456@u.nus.edu
• NAME is case-sensitive.
  • e.g. John Doe is different from john doe
• GRADE should be one of the valid grades: [A+, A, A-, B+, B, B-, C+, C, D+, D, F].
• Editing GROUP will overwrite existing GROUP entries.
• Use of GROUP prefix gp/ in an edit command without specifying GROUP_NAME will clear all existing GROUPs of the student!
• This feature is only applicable to the archived list.

Examples:

• edit_archived A0123459X g/B e/e0237861@u.nus.edu edits the grade of the student with STUDENT_ID = A0123459X to “B” and the EMAIL to “e0237861@u.nus.edu”.

Expected output:

7.10.3 Deleting an archived student : delete_archived

Deletes an archived student from the archived list.

Format: delete_archived STUDENT_ID

• Deletes an archived student with the specified STUDENT_ID.
• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• The student with the specified STUDENT_ID must exist in the archived list.
• This feature is only applicable to the archived list.

Example:

• delete_archived A0123459X deletes the student with STUDENT_ID = A0123459X from the archived list.

Expected output:

7.10.4 Unarchiving a student : unarchived

Unarchives a student from the archived list. That student is moved to the persons list.

Format: unarchived STUDENT_ID

• Unarchives a student with the specified STUDENT_ID.
• STUDENT_ID should start with ‘A’, followed by 7 digits, and end with any capital letter.
  • e.g. A0123459X
• The student with the specified STUDENT_ID must exist in the archived list.
• This feature is only applicable to the archived list.

Examples:

• unarchived A0123459X unarchives a student with the student_id = A0123459X.

Expected output:

7.10.5 Clearing all entries : clear_archived

Clears all entries from the archived list.

• This feature is only applicable to the archived list.

Format: clear_archived

7.11 Exiting the program : exit

Exits the program.

Format: exit

7.12 Saving the data

TeachStack data is saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

7.13 Editing the data files

TeachStack data is saved automatically as a JSON file [JAR file location]/data/addressbook.json and [JAR file location]/data/userdata.json. Advanced users are welcome to update data directly by editing that data file.

Caution: If your changes to the data files makes its format invalid, TeachStack will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it.
Furthermore, certain edits can cause the TeachStack to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly. Teachstack cannot take any responsibility for corrupted data if you choose to modify the data files directly.

7.14 Setting weak threshold : setweak

Sets the weakness threshold for a weak marker. The weakness threshold is the minimum grade for a student to be considered weak.

Format: setweak g/GRADE

• By default, weakness threshold is set at Grade: C+
• The command updates the weakness threshold value.
• Students with grade lower than or equal to the threshold grade appear with a marker in the UI. Look at the below image to see an example.

• GRADE should be one of the valid grades: [A+, A, A-, B+, B, B-, C+, C, D+, D, F].
• After setting the threshold with the command, the weak marker will be maintained even after shutting down the application.
• Do note that the setweak command does not affect archived students. This means weak labels on archived students will not be changed.

Example:

• setweak g/B displays a weak marker for all students with grade B or lower.

Before command (Default Weakness Threshold)

After command setweak B

Dorian Grey now has a weak marker which was not there previously, as we just changed the weak threshold to B.

7.15 Viewing summary statistics : summary

Displays a summary of all students.

Format: summary

• Entering the command opens a popup window.
• The new window contains statistics: Total Students, Average Grade, and Standard Deviation of Grades.
• It also contains a pie chart of students’ grades.
  • If there are 0 students, the pie chart does not display.
• Do note that the summary command does not consider archived students.

Displayed after the command: summary

8. Glossary

• GUI: Graphical User Interface. An interface that uses visual representations, such as icons, buttons and windows where users can use to interact with the system.
• CLI: Command Line Interface. A text-based interface that allows users to interact with the application by typing commands. Command is parsed to the system when users hit Enter.
• JAR: Java Archive. Package file format used to aggregate the Java class files and associated metadata and resources required to run TeachStack into one file to distribute the application.
• Student: Student studying at NUS and instructed by the user.
• Student ID: Unique matriculation number of an NUS student. TeachStack only accepts a student id that starts with ‘A’, followed by 7 consecutive digits and ends with a capital letter ‘[A-Z]’.
• Email: An electronic mail address. TeachSTack only accepts NUS email addresses in the format ‘eXXXXXXX@u.nus.edu’ where ‘X’ can be any digit.
• Grade: A letter that shows how good a student’s performance is. TeachStack only accepts grades that exist in the NUS grading system ([A+, A, A-, B+, B, B-, C+, C, D+, D, F]).
• Name: Name of a student. TeachStack only accepts name consisting of alphabets, numbers and space.
• Focus group: Group of students such that the user can pay more attention to assist the students in the group. Indicated by a Group label on the GUI
• Student details: The student’s NAME, STUDENT_ID, EMAIL, GRADE, and focus group (GROUP) that the student belongs to, if any.
• Grade threshold: A threshold used by the system to determine if a student is considered as weak based on their grades. If the student’s grade falls below, or is at the threshold, the student is considered as weak. It is set to C+ by default. The user can update the threshold using the setweak command according to their preference.
• Summary statistics: Statistics of all active students (not in archived list), including the total number of students, mean grade, standard deviation of grade and a pie chart showing grade distribution.

9. FAQ

9.1 General concerns

Q: Is TeachStack free to use?
A: Yes! TeachStack is completely free to use. We believe in making student management accessible to all computer science instructors. Enjoy the full functionality of TeachStack without any subscription fees or hidden charges.

Q: I am facing issues/want to give suggestions for TeachStack. How can I resolve them?
A: Not to worry! Our developer team is committed to ensuring the best experience for instructors like you. Please submit any issues/suggestions you might have to our Google form here. Alternatively, you can also file them on our Github repository here. We appreciate your feedback and will respond as soon as possible.

Q: Is TeachStack suitable for use for computer science instructors outside of NUS?
A: For now, the application is only meant to be used within NUS. However, we do plan to make improvements to allow all computer science instructors, regardless of educational institution, to utilise the application, so do keep an eye out for future developments!

Q: Is TeachStack suitable for Teaching Assistants (TAs)?
A: While TeachStack is currently tailored for computer science instructors to simplify managing large student bodies, TAs may also find our app useful, especially in scenarios with larger class sizes. We continually strive to expand TeachStack’s capabilities to better serve the diverse needs of educators and teaching teams.

Q: Is TeachStack really better than Canvas, Excel, etc. for me?
A: Yes! While the other platforms do offer valuable features, TeachStack stands out with its CLI, intuitive group forming, archiving, and other tailored features designed specifically for computer science educators. What sets TeachStack apart is our commitment to continuous improvement and development, driven by your feedback. With ongoing enhancements, we’re dedicated to ensuring TeachStack remains the preferred choice for instructors seeking to elevate their teaching experience.

9.2 Using TeachStack

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 TeachStack home folder.

Q: I made changes to the data files manually, and I am now facing errors! What should I do?
A: We recommend that you only manually edit the files if you are confident that you can update it correctly. In the event that you run into errors after manually editing the files, please delete the [JAR file location]/data folder so TeachStack can create new files.

Q: Do I have to save my changes manually?
A: No, TeachStack will automatically save any changes you have made after a command is entered.

10. Known issues

1. When using multiple screens, if you move the application to a secondary screen, and later switch to using only the primary screen, the GUI will open off-screen. The remedy is to delete the preferences.json file created by the application before running the application again.

11. Command summary