PROJECT: Notably

Overview

Notably is for those who prefer to use a desktop app for managing contacts. More importantly, Notably 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, Notably can get your notes taken down faster than traditional GUI apps.

Summary of contributions

  • Major enhancement: Added Parser and Command of the system.

    • What it does: Integrate the features implemented by my team mate to one system and make sense of the user input.

    • Justification: This enhancement improve the user experience and is crucial to detect and prevent any unintended changes.

    • Highlights: This enhancement allow the user experience to be more intuitive and is designed similar to the terminal that we are familiar with. It required an in-depth analysis of the existing design alternatives. The implementation too was challenging as it required multiple new predicate and utility classes.

  • Major enhancement: Path data structure.

    • What it does: Allow the user different form of traversal methods (Either relative to the current directory or to the root).

    • Justification: This feature boosts the productivity of the user significantly because user can type less to traverse into a block. For example, the user can type o cs2103T/tutorials/tutorial2 to open 3 nested blocks rather than typing 3 commands .

    • Highlights: This enhancement allow the user experience to be more intuitive and is designed similar to the terminal that we are familiar with. It required an in-depth analysis of the existing design alternatives.

  • Minor enhancement:

    • Add optional Prefix to enhance user experience.

    • Tested the integrated features implemented by my group members.

    • Add Logger to parser and Command to help future development.

  • Code contributed: [Functional code]

  • Other contributions:

    • Project management:

      • Release Notably v1.4 on GitHub

    • Enhancements to existing features:

      • Rewrote complex test cases to improve test coverage significantly #291

      • Added commonly used methods to Parser’s utility class. #181

    • Documentation:

      • Help setup the draft for User Guide #11

      • Updated User Guide and Developer Guide

    • Community:

      • Reported bugs and suggestions for other teams in the class (examples: #210, #212, #07 )

      • Some parts of the Path feature I added was adopted by several other class mates #65

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Paths

  • Paths are used to specify the location of a note you want the Command to be pointed at.

  • There are 2 types of Path namely:

    • AbsolutePath (which takes reference from the root, as shown in Figure 2 below)

    • RelativePath (which takes reference from the current note)

/ represents a root note

The RelativePath operates similarly to the command line input that you may be familiar with. Listed below are the notations used to define a RelativePath.

  • . (Point to current note)

  • .. (Point to parent note)

  • exampleNote (Point to child node)

Validity of Paths

  • AbsolutePath

    • Must start with the root note.

    • After every / you can provide a Title (Valid Title).

    • /Workspace/2103T is a valid AbsolutePath, Workspace/2103T is not.

  • Relative Path

    • Starts with . or .. or a Title (Valid Title).

    • ./CS2103T/../CS2101 is a valid RelativePath.

Example

The picture below helps to illustrate the use of RelativePath and AbsolutePath

UGPathDiagram
Figure 1. Example to illustrate Path

The AbsolutePath /Workspace/CS2101 is equivalent to RelativePath ../CS2101

Thus open /Workspace/CS2101 and open ../CS2101 would yield the same result.

Paths are used by the open and delete command
The Root simply serves as a way for Notably to hierarchically organise your notes. It will not be visible to you while you are using the application.
You cannot delete the root note. e.g Delete ../.. is invalid. An error message will be displayed to remind you of this.

=== Open an existing note: open

You can open an existing note by specifying its absolute or relative path).

Format: open [-t] AbsolutePath/Relativepath

  • If you want to save some keypresses, omit the optional -t flag. It still works fine!

==== Example: Opening a note . Let’s open the note Notably that exists in the currently opened note Workspace (Step 1) with the command:

open -t Notably

  • Notably gives you some useful suggestions on other paths that are similar or related to your input!

Open
Figure 2. Step 1 - Demo for the open command (with suggestions)

== Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

==== NotablyParser component

LogicClassDiagram
Figure 3. Class Diagram of the Logic Component

  1. Logic uses the NotablyParser class to parse the user command.

  2. This results in a List<Command> object which is executed by the LogicManager.

  3. The command execution can affect the Model (e.g. adding a Note).

  4. The updated model/data structure will automatically be reflected on to the View.

Given below is the Sequence Diagram for interactions within the Logic component for the execute("delte -t cs2103") API call.

DeleteSequenceDiagram
Figure 4. Interactions Inside the Logic Component for the delte -t cs2103 Command
The lifeline for DeleteCommandParser should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.

=== Paths Given below is the implementation detail of the Path feature and some alternative design considerations.

==== Current Implementation The Path interface represents the location of a Block in our data structure. A path can exist in 2 forms namely :

  1. AbsolutePath

  2. RelativePath

An AbsolutePath is a path that takes its reference from the root / block.
While a RelativePath takes it reference from the current note that is opened.

Currently the user is given the freedom to provide any of the 2 forms when using the open, delete command.
Given the following DataStructure below.

PathExample1
Figure 5. DataStructure example to illustrate Path

Using AbsolutePath open /CS2101 and using RelativePath open ../CS2101 would yield the same result.

==== Design Consideration

Aspect: Implementation of Path :

  • Alternative 1(Current choice): Have 2 separate class implementing Path, which is AbsolutePath and RelativePath.

    • Pros: More readable and OOP, each class can have their individual validity REGEX.

  • Alternative 2: Implement a single class PathImpl and have a boolean flag isAbsolute to tell if its a Relative or Absolute path.

Aspect: Logical equivalence of RelativePath :

  • Alternative 1(Current choice): Relative path CS2103/../note1 would be equivalent to note1.

    • Pros: More intuitive for the user and developer, making it easier to integrate paths with other features.

  • Alternative 2: Relative path CS2103/../note1 would not be logically equivalent to note1.

== Product Scope

Target user profile:

  • Students that has a need to take notes and organize them into categories

  • prefer desktop apps over other types

  • can type fast

  • prefers typing over mouse input

  • is reasonably comfortable using CLI apps

Value proposition: Take and manage notes faster than a typical mouse/GUI driven app

== User Stories

Priorities: High (must have) - * * *, Medium (nice to have) - * *, Low (unlikely to have) - *

Priority As a …​ I want to …​ So that I can…​

* * *

student

traverse my notes in a file system-like manner

so that I can skim through my sea of notes and drafts without any problem.

* * *

student

search my notes by their content

I won’t have to remember the exact location and title of notes.

* * *

student

reliably type search commands(not error-prone)

focus on searching my notes rather than ensuring my commands are exact

* *

student

can quickly make changes to a note

so that I can update my notes with new information accurately while in class.

*

impatient student

alias a path to a folder

do not have to memorise and type out the entire file structure when accessing a nested note

== Instructions for Manual Testing

Given below are instructions to test the app manually.

These instructions only provide a starting point for testers to work on; testers are expected to do more exploratory testing.

=== Launch and Shutdown

  1. Initial launch

    1. Download the jar file and copy into an empty folder

    2. Double-click the jar file
      Expected: Shows the GUI with a set of sample Notes. The window size may not be optimum.

  2. Saving window preferences

    1. Resize the window to an optimum size. Move the window to a different location. Close the window.

    2. Re-launch the app by double-clicking the jar file.
      Expected: The most recent window size and location is retained.

=== Add a new Note . Adding a new Note to Notably without immediately opening that Note.

  1. Prerequisites: None of the child(ren) Note(s) of the currently opened Note has the same title as the new Note.
    Moreover, the currently opened Note must be the directory where the user wants to store the new Note.

  2. Command: new -t Notably
    Expected: a new Note titled "Notably" is added to the currently opened Note. The currently opened Note (current working directory) remains the same (highlighted at the sidebar).

    1. Adding a new Note to Notably and immediately opening that Note

  3. Prerequisites: None of the child(ren) Note(s) of the currently opened Note has the same title as the new Note.
    Moreover, the currently opened Note must be the directory where the user wants to store the new Note.

  4. Command: new -t Notably -o
    Expected: a new Note titled "Notably" is added to the currently opened Note. The currently opened Note (current working directory) is now the newly created "Notably" note (highlighted at the sidebar).

=== Open a Note . Opening a Note in Notably.

  1. Prerequisites: The Note that is about to be opened must not be the root Note.

  2. Command: open [-t] Notably
    Expected: The Note titled "Notably" will be opened, with its content being displayed in the UI. The label "Notably" at the sidebar will also be highlighted, to indicate that the Note is being opened.

=== Delete a Note . Deleting a Note in Notably.

  1. Prerequisites: The Note that is about to be deleted must not be the root Note.

  2. Command: delete [-t] Notably
    Expected: The Note titled "Notably" will be deleted. The other nested Notes inside the Note "Notably" will also be deleted.
    The Note "Notably" will no longer be visible in the sidebar.

=== Edit a Note . Editing a Note in Notably.

  1. Prerequisites: The Note that is about to be edited must not be the root Note.
    The currently opened Note must be the Note that the user wants to edit.

  2. Command: edit
    Expected: An edit modal will pop up displaying your Note’s content in HTML format. The user can edit and save the Note by exiting that modal.

=== Search for a Note based on a keyword . Searching for a note by using a keyword in Notably.

  1. Prerequisites: -

  2. Command: search [-s] hello
    Expected: A list of suggestions will be displayed, sorted based on the number of keyword matches, i.e. the note having the highest number of "hello" in its body will be put at the top of the suggestion list.

=== Correct command . Correct command word in user input.

  1. Prerequisites: There should exist a Note titled Notably.

  2. Command: 'delete [-t] Notably'

  3. Expected: The command is interpreted as a delete command by Notably.

    1. Correct path in user input.

  4. Prerequisites: There should exist a Note titled Notably.

  5. Command: 'delete [-t] Notbly'

  6. Expected: The command is interpreted as a delete command by Notably.