Skip to content

Latest commit

 

History

History
1298 lines (869 loc) · 54.8 KB

DeveloperGuide.adoc

File metadata and controls

1298 lines (869 loc) · 54.8 KB
Raw

ResuMaker - Developer Guide

By: CS2103-W-17-1      Since: August 2018      Licence: MIT

1. Introduction

Welcome to the Developer Guide for ResuMaker - a fast and flexible resume generator! This Guide contains essential information for those seeking to maintain, or enhance ResuMaker.

Developers new to ResuMaker can refer to Setting Up to get started.
Experienced developers can find advanced details in Section 2 and Section 3.

2. Setting up

2.1. Prerequisites

  1. JDK 9 or later

    ⚠️
    		 JDK 10 on Windows will fail to run tests in headless mode due to a JavaFX bug. Windows developers are highly recommended to use JDK 9.

  2. IntelliJ IDE

    ℹ️
    		 IntelliJ by default has Gradle and JavaFx plugins installed.
    Do not disable them. If you have disabled them, go to File > Settings > Plugins to re-enable them.

2.2. Setting up the project in your computer

Follow these steps to set up the project in your computer for development:

  1. Fork this repo, and clone the fork to your computer

  2. Open IntelliJ (if you are not in the welcome screen, click File > Close Project to close the existing project dialog first)

  3. Set up the correct JDK version for Gradle

    1. Click Configure > Project Defaults > Project Structure

    2. Click New…​ and find the directory of the JDK

  4. Click Import Project

  5. Locate the build.gradle file and select it. Click OK

  6. Click Open as Project

  7. Click OK to accept the default settings

  8. Open a console and run the command gradlew processResources (Mac/Linux: ./gradlew processResources). It should finish with the BUILD SUCCESSFUL message.
    This will generate all resources required by the application and tests.

2.3. Verifying the setup

To verify that you have setup the project correctly:

  1. Run the seedu.address.MainApp and try a few commands

  2. Run the tests to ensure they all pass.

2.4. Configurations to do before writing code

2.4.1. Configuring the coding style

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

  1. Go to File > Settings…​ (Windows/Linux), or IntelliJ IDEA > Preferences…​ (macOS)

  2. Select Editor > Code Style > Java

  3. Click on the Imports tab to set the order

    • For Class count to use import with '*' and Names count to use static import with '*': Set to 999 to prevent IntelliJ from contracting the import statements

    • For Import Layout: The order is import static all other imports, import java.*, import javax.*, import org.*, import com.*, import all other imports. Add a <blank line> between each import

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

2.4.2. Updating documentation to match your fork

After forking the repo, the documentation will still have the SE-EDU branding and refer to the se-edu/addressbook-level4 repo.

If you plan to develop this fork as a separate product (i.e. instead of contributing to se-edu/addressbook-level4), you should do the following:

  1. Configure the site-wide documentation settings in build.gradle, such as the site-name, to suit your own project.

  2. Replace the URL in the attribute repoURL in DeveloperGuide.adoc and UserGuide.adoc with the URL of your fork.

2.4.3. Setting up CI

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

After setting up Travis, you can optionally set up coverage reporting for your team fork (see UsingCoveralls.adoc).

ℹ️
 Coverage reporting could be useful for a team repository that hosts the final version but it is not that useful for your personal fork.

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

ℹ️
 Having both Travis and AppVeyor ensures your App works on both Unix-based platforms and Windows-based platforms (Travis is Unix-based and AppVeyor is Windows-based)

2.4.4. Getting started with coding

When you are ready to start coding, get some sense of the overall design by reading Section 3.1, “Architecture”.

3. Design

3.1. Architecture

Architecture
Figure 1. Architecture Diagram

The Architecture Diagram given above explains the high-level design of the App. Given below is a quick overview of each component.

💡
 The .pptx files used to create diagrams in this document can be found in the diagrams folder. To update a diagram, modify the diagram in the pptx file, select the objects of the diagram, and choose Save as picture.

Main has only one class called MainApp. It is responsible for,

  • At app launch: Initializes the components in the correct sequence, and connects them up with each other.

  • At shut down: Shuts down the components and invokes cleanup method where necessary.

Commons represents a collection of classes used by multiple other components. Two of those classes play important roles at the architecture level.

  • EventsCenter : This class (written using Google’s Event Bus library) is used by components to communicate with other components using events (i.e. a form of Event Driven design)

  • LogsCenter : Used by many classes to write log messages to the App’s log file.

The rest of the App consists of four components.

  • UI: Displays the App’s User Interface.

  • Logic: Executes Commands.

  • Model: Holds the data of the App in-memory.

  • Storage: Reads data from, and writes data to, the hard disk.

Each of these four components:

  • Defines its API in an interface with the same name as the Component.

  • Exposes its functionality using a {Component Name}Manager class.

For example, the Logic component (see the class diagram given below) defines it’s API in the Logic.java interface and exposes its functionality using the LogicManager.java class.

LogicClassDiagram
Figure 2. Class Diagram of the Logic Component

Events-Driven nature of the design

The Sequence Diagram below shows how the components interact for the scenario where the user issues the command delete 1.

SDforDeletePerson
Figure 3. Component interactions for delete 1 command (part 1)
ℹ️
 Note how the Model component simply raises a AddressBookChangedEvent when the Address Book data are changed, instead of asking the Storage to save the updates to the hard disk.

The diagram below shows how the EventsCenter reacts to that event, which eventually results in the updates being saved to the hard disk and the status bar of the UI being updated to reflect the 'Last Updated' time.

SDforDeletePersonEventHandling
Figure 4. Component interactions for delete 1 command (part 2)
ℹ️
 Note how the event is propagated through the EventsCenter to the Storage and UI without Model having to be coupled to either of them. This is an example of how this Event Driven approach helps us reduce direct coupling between components.

The sections below give more details of each component.

3.2. UI component

UiClassDiagram
Figure 5. Structure of the UI Component

API : Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PersonListPanel, StatusBarFooter, BrowserPanel etc. All these, including the MainWindow, inherit from the abstract UiPart class.

The UI component uses JavaFx UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the MainWindow is specified in MainWindow.fxml

The UI component,

  • Executes user commands using the Logic component.

  • Binds itself to some data in the Model so that the UI can auto-update when data in the Model change.

  • Responds to events raised from various parts of the App and updates the UI accordingly.

3.3. Logic component

LogicClassDiagram
Figure 6. Structure of the Logic Component

API : Logic.java

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

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

  3. The command execution can affect the Model (e.g. adding a person) and/or raise events.

  4. The result of the command execution is encapsulated as a CommandResult object which is passed back to the Ui.

Given below is the Sequence Diagram for interactions within the Logic component for the execute("delete 1") API call.

DeletePersonSdForLogic
Figure 7. Interactions Inside the Logic Component for the delete 1 Command

3.4. Model component

ModelClassDiagram
Figure 8. Structure of the Model Component

API : Model.java

The Model,

  • stores a UserPref object that represents the user’s preferences.

  • stores the Address Book data.

  • exposes an unmodifiable ObservableList<Person> that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change.

  • does not depend on any of the other three components.

ℹ️
 As a more OOP model, we can store a Tag list in Address Book, which Person can reference. This would allow Address Book to only require one Tag object per unique Tag, instead of each Person needing their own Tag object. An example of how such a model may look like is given below.

ModelClassBetterOopDiagram

3.5. Storage component

StorageClassDiagram
Figure 9. Structure of the Storage Component

API : Storage.java

The Storage component,

  • can save UserPref objects in json format and read it back.

  • can save the Address Book data in xml format and read it back.

3.6. Common classes

Classes used by multiple components are in the seedu.addressbook.commons package.

4. Implementation

This section describes some noteworthy details on how certain features are implemented.

4.1. Tags and Categories

Tags and categories are single-word keywords tied to individual entries. Each ResumeEntry can be classified under one Category, but can be associated with multiple Tag.

4.1.1. Categories

Category related functions are mainly contained in the seedu.address.model.category package, which includes the Category class and its relevant CategoryManager. CategoryManager is used by the ModelManager (seedu.address.model.ModelManager) to filter the list of entries by categories.

Filtering can be done by passing the relevant Predicate<ResumeEntry> into CategoryManager through CategoryManger.setPredicate(). The relevant filtered list can be obtained by subsequently calling CategoryManager.getList().

4.1.2. CategoryManager

To use CategoryManager to filter out relevant entries, there are a few main functions to keep in mind:

  • setList(List<ResumeEntry> entries): sets the source list of entries to filter

  • getList(): returns unmodifiableObservableList<ResumeEntry> of relevant entries

  • setPredicate(Predicate<ResumeEntry> predicate): sets the filtering criteria for the list of entries

  • mkPredicate(Predicate<ResumeEntry> predicate, String category): returns a predicate that builds onto the given predicate to filter by given category as well

  • mkPredicate(String category): return a predicate that filters entries by the category

Example: Listing entries from a certain category tag ls ~work

CategoryManager can be used to filter out certain entries for display in the UI.

CategoryManager categoryManager = new CategoryManager();
Predicate<ResumeEntry> predicate = categoryManager.mkPredicate("work");
modelManager.updateFilteredEntryList(predicate);

  • A Predicate<ResumeEntry> will be generated by the command using CategoryManager.mkPredicate()

  • This predicate is then passed along to Model.filteredEntryList for the that the display can be updated

  • The diagram below illustrate the flow of the program if one were to implement use it in a Command

categoryManager example listEntry
Figure 10. Program flow for listing entries
Example: Filtering entries to be written to resume

CategoryManager can be used to extract out the relevant resume entries to be included in the specific sections of the resume.

TagManager tagManager = new TagManager();
CategoryManager categoryManager = new CategoryManager();

categoryManager.setList(modelManager.getFullList());
categoryManager.setPredicate(categoryManager.mkPredicate(category));

tagManager.setList(categoryManager.getList());
tagManager.setPredicate(tagManager.mkPredicate(tags));
List<ResumeEntry> filtered = tagManager.getList();

  • The full list obtained from Model.filteredList will be passed into the CategoryManger through CategoryManager.setList()

  • Based on the filters on different sections of the template, a specific Predicate<ResumeEntry> will be created for that section

  • The Predicate<ResumeEntry> created will be passed into the CategoryManager through CategoryManager.setPredicate()

  • The list of entries to be printed will be retrieved through CategoryManager.getList()

  • If there is further filtering to be done on tags, the same set of steps will be done on TagManager

  • The diagram below illustrate the flow of the program if one were to implement use it in a Command

categoryManager example template
Figure 11. Program flow for filtering out entries for resume generation

4.1.3. Predicates

The CategoryManager was written to help developers filter out desired predicates easily. As such, the CategoryManager.mkPredicate() is written to return a Predicate<ResumeEntry> which can be passed into other functions for the filtering process, be it for display or resume generation process.

There are two general forms of the function, mkPredicate<String category> and mkPredicate(Predicate<ResumeEntry> entries, String category).

The first form of the function returns a predicate which returns true if the ResumeEntry.getCategory().cateName == category. In short, it will filter out entries of a particular category.

The second form of the function (mkPredicate(Predicate<ResumeEntry> predicate, String category)) extends the existing predicate and implement the category checking process on top of it. For the new predicate to return true, the ResumeEntry must fulfill the first Predicate<ResumeEntry> and also be of a particular specified category.

Example: Filtering entries using both tags and category tag ls ~work #java #python

This function is used to implement more complex filters, for example, when entries needs to be filtered by both tags and categories in tag ls.

TagManager tagManager = new TagManager();
CategoryManager categoryManager = new CategoryManager();

Predicate<ResumeEntry> predicate = categoryManager.mkPredicate(category);
predicate = tagManager.mkPredicate(predicate, tags);
modelManager.updateFilteredEntryList(predicate);

  • A Predicate<ResumeEntry> will be generated by the command using CategoryManager.mkPredicate()

  • This predicate is then passed along to TagManager.mkPredicate() to be extended to include tag filtering

  • The combined predicate is passed to Model.filteredList for the display to be updated

  • The diagram below illustrate the flow of the program if one were to implement use it in a Command

categoryManager example tagls
Figure 12. Program flow for filtering out entries for both tag and category

4.1.4. Design considerations

There are 2 main ways to implement entries filtering: within CategoryManager itself or using CategoryManager to generate Predicate<ResumeEntry> to be used for filtering. Below are some evaluation as to why and when each of the methods may be relevant.

Alternative 1: Handles all the entries filtering within CategoryManager

This is implemented through setList(), setPredicate() and getList(). The full list of entries is passed in, and the filtered list of entries is returned. This will typically be used in the filtering of the entries in the resume generation process.

This method is much cleaner, encapsulating all the filtering process within CategoryManger. But if we are sticking to the current implementation of displaying the UI from a FilteredList<ResumeEntry>, this approach may not be appropriate, hence, the second alternative implementation, which gracefully handles this case.

Example:

  • setList(List<ResumeEntry>) to set the full list of entries to filter from

  • setPredicate(mkPredicate(category)) to filter list based on category

  • getList() to return list of filtered entries

Alternative 2: Using CategoryManager to build the desired Predicate

This is implemented through mkPredicate(). The function is used to build upon a given Predicate<ResumeEntry>. which can be passed into ModelManager.updateFilteredEntryBook() to filter the displayed list of entries in the UI.

This method allow us to utilize the original UI mechanism for updating the displaying using a predicate, instead of having to alter the list of entries over and over again.

Example:

  • Predicate<ResumeEntry> obtained that does some preliminary filtering (e.g. filtering based on tags)

  • mkPredicate(predicate, category) extends the original predicate to further filter by category

  • ModelManager.updateFilteredEntryList(predicate) to update view of displayed entries

Current Implementation

Currently, a mixture of these functions are implemented. This allows the developers to use CategoryManager in both manner, whichever method they deem more appropriate.

4.2. Templates

A template specifies the format of the generated resume. It specifies the sections in the resume, and which entries should be included under each section based on a set of tags.

4.2.1. Template object structure

The diagram below shows the structure of a Template object. A Template contains an ArrayList of TemplateSection, where each contains a title to be displayed and two predicates for filtering entries based on their category and tags.

Template UML
Figure 13. Template object UML class diagram

4.2.2. Template file

Templates are stored as text files, with each line in the following format:

[Category Heading]:~[Category Tag]:[Tag Groups]

The list of tags in [Tag Groups] can be treated as a sum of products form, where a & represents AND and space represents OR. If no tags are specified, all entries with the [Category Tag] will be included.

Template files are written by the user and loaded into the application using the loadtemplate command.

4.2.3. Template loading sequence

The diagram below shows how the components interact when the user attempts to load a template using the loadtemplate template1.txt command.

Template SD1
Figure 14. Component interactions for loadtemplate template1.txt command (part 1)

The diagram below shows how EventsCenter reacts, raising a TemplateLoadRequestedEvent which prompts Storage to attempt to load the template from file. If the loading was successful, it the text file will be parsed into a Template object, and passed into the TemplateLoadedEvent. This event will be handled in the Model, which will store the Template retrieved from the event. Otherwise, a TemplateLoadingExceptionEvent will be raised and handled by Model as well.

Template SD2
Figure 15. Component interactions for loadtemplate template1.txt command (part 2)

4.3. Entry Management

This section describes the implementation of features related to managing entries in ResuMaker, and explains the underlying classes and supporting data structures.

4.3.1. Construct Entry Related Classes

Below is the class diagram of classes under the package seedu.address.model.entry, which lays the foundation for the implementation of Entry Management

classDiagramForEntry
Figure 16. Class diagram for entry related classes

  • Current Implementation

    1. As shown in the diagram, all data of an added entry in ResuMaker is encapsulated as a class ResumeEntry, which is composed of four other classes: namely one Category, one EntryInfo, one EntryDescription and multiple instances of Tag.

    2. ResuMaker extends a Taggable interface which allows manipulation of tags associated with itself.

  • Design Consideration

    1. Taggable Interface
      Provides an additional abstraction layer for any class that needs to access methods that ResumeEntry overrides to implement Taggable. This enforces Interface Segregation Principle in which unrelated classes have limited knowledge about ResumeEntry.

    2. Encapsulation of EntryInfo

      1. Instead of lumping title, subtitle and duration in ResumeEntry, encapsulating the three into EntryInfo provides another layer of abstraction.

      2. Not all entries have the three information, a minor entry does not contain title, subtitle or duration. EntryInfo helps to differentiate minor entry from major entry using isMinorEntry().

    3. Encapsulation using EntryDescription

      1. As opposed to putting an entry description as a String field in ResumeEntry, encapsulating it in EntryDescription provides another layer of abstraction.

      2. EntryDescription contains List<String> that allows for easy modification of a specific segment of the description of a particular entry, i.e. allows users to edit a particular line of description in that entry.

4.3.2. Responsive Display of Expanded Entry

This enhancement enables the Graphic User Interface to display the description of an entry responsively to any modification of an entry.

  • Current Implementation

    1. The high level interaction between different components follows the same workflow as any other commands.
      Diagram(part a) below illustrates the high level interaction between different components when an addBullet or editBullet command is executed.

    2. A noteworthy point is that it makes use of event driven design to allow UI to respond to Logic. EventCenter acts as the receiver of the three events raised by Logic and sends them to the respective handlers of these events. For addBullet command, the handlers of events raised are UI and Storage. Please refer to diagram(part b) below for more detail.

SequenceDiagramAddBullet 1
Figure 17. Sequence diagram for adding a bullet description to an entry (part a)
SequenceDiagramAddBullet 2
Figure 18. Sequence diagram for adding a bullet description to an entry (part b)

  • Design Consideration

    1. Minimizing the amount of code to be added by tapping on the existing utility
      Given how well-established event driven approach is, it will be more convenient to adopt it to minimize the addition of lines of code. Taking the alternative would mean extra code to be added to establish some form of reference of UI in Logic.

    2. Decoupling between Logic and UI
      Rather than asking Logic to interact directly with UI to request for changes in UI, which increases coupling between the two, EventCenter acts as the "middle man" to minimize coupling.

4.4. Resume Generation

This section describes the implementation of the resume generation feature, explains the underlying classes and supporting data structures, and highlights areas that are open to extension.

4.4.1. Resume Structure

The Resume contains a list of ResumeSections, each comprising a title and a list of ResumeEntries associated with it (as stipulated by the Template used to generate the Resume).
[CLASS DIAGRAM]

4.4.2. Storage Management

When a resume is to be saved to a file, the ModelManager raises a ResumeSaveEvent, which encapsulates the complete Resume as well as the specified file Path. This event is captured by the StorageManager, which passes the data to the MarkdownResumeStorage class. The Resume object is then converted to a markdown String by the MarkdownConverter utility class, after which it is written to a file (with the specified name) by the MdUtil class.
[DIAGRAM]

4.4.3. Markdown Conversion

To transform this abstract object representation of the Resume into concrete text, the MarkdownConverter utility class progressively converts each level of the Resume (from the titles, information and descriptions of each individual ResumeEntry, to a ResumeSection of ResumeEntries and finally the full Resume) into a String containing its formatted markdown representation.

An external Java Markdown Generator library was used to handle the generation of the markdown String in MarkdownConverter, as it was built on a Builder pattern which made it easier and more organised to progressively generate markdown text for each part of the resume and combine it all together in the end.

4.4.4. Possible Extensions

Changing Markdown Layouts

If you wish to modify the markdown layout produced by ResuMaker, look into the overloaded toMarkdown method within MarkdownConverter. The various versions of this method are implemented using the Java Markdown Generator external library and designed to be easy to understand and modify.
You are recommended to create a new subclass of MarkdownConverter and @Override its toMarkdown method with your own versions, so as to preserve the original functionality of the application for reference.

Adding File Formats

While we have chosen to implement conversion into markdown, you may prefer a different file format and want to avoid the hassle of converting markdown to other formats outside the application. To this end, you can extend ResuMaker by adding support for saving Resumes to a new format.
To achieve this, you would have to design your own class implementing the ResumeStorage interface. This new class would then need new utility methods to handle conversion of the Resume into another text format, such as XML.
[DIAGRAM OF NECESSARY ADDITIONS]

4.5. Contextual Awareness

4.5.1. Key Terms

Here are some terms that are used often when discussing Contexual Awareness.
Please review their definitions in the Glossary before reading further.

4.5.2. Overview

Contextual Awareness enables ResuMaker to:

  • Create pre-filled ResumeEntries for standard Events.

  • Understand slang and partial phrases in the user’s input.

The flowchart below illustrates the overall flow taken by an end-user when working with the Contextual Awareness feature.

AwarenessFlow

The flowchart highlights the 4 separate steps involved in the Contextual Awareness feature:

  1. Providing feedback to the user, as he types in an <expression>.

  2. Guessing an Event name, based on the user provided <expression>.

  3. Matching the guessed Event name, with an actual Event, as defined in the user provided data.

  4. Creating a ResumeEntry for the matched Event.

In this guide, we will discuss Steps 2, and 3.

4.5.3. Guessing an Event name, based on user provided <expression>

To guess the Event name, we parse the slang, partial phrases and full phrases in the expression to get a possibleEventName. This parsing is done by the Awareness class.

As shown earlier, an instance of the Awareness class is initialised from user provided XML data, upon startup.

The following Figure shows the structure of the Awareness class.

awarenessStructure

Parsing the slang, partial phrases and full phrases is a 2-step process:

First, use the dictionary (see Figure) to replace each slang with its corresponding full phrase.
After this step, the expression will only contain partial phrases and full phrases.
Now, replace each partial phrase with its corresponding full phrase.

This gives us a string of full phrases, which is our possibleEventName.

As an example, suppose our initial expression was: ug research assist. In this expression, we have:

  • A slang (ug - slang for undegraduate)

  • A partial phrase (assist - short for assistant)

  • A full phrase (research)

After the first step, our expression will be undergraduate research assist.
After the second step, our expression will be undergraduate research assistant
Thus, our possibleEventName will be undergraduate research assistant.

4.5.4. Matching the guessed Event Name, with an actual Event [Work In Progress]

Work in Progress

4.5.5. Design Choices

ContextCommand

The ContextCommand is constructed by passing it a CommandSupplier. This construction is done by ContextCommandParser. When it is time to execute the ContextCommand, the CommandSupplier supplies the relevant command.

Pros:

  • ContextCommand can be decoupled from specific commands like AddCommand.

  • ContextCommand can be extended to perform any type of Command, by passing the relevant CommandSupplier.

Alternatives:

  • Create different types of ContextCommands for different purpose: i.e. ContextAddCommand, ContextFindCommand, etc

The alternative may be equally valid.

Awareness class

The Awareness class is constructed by passing it a Dictionary containing slang - full phrase mappings.

Alternatives:

  • Create the Dictionary instance within the constructor of Awareness, rather than accepting it.

Pros:

  • Increased testability as the dependancy (Dictionary object) can be controlled since it is passed into the constructor.

4.6. Logging

We are using java.util.logging package for logging. The LogsCenter class is used to manage the logging levels and logging destinations.

  • The logging level can be controlled using the logLevel setting in the configuration file (See Section 4.7, “Configuration”)

  • The Logger for a class can be obtained using LogsCenter.getLogger(Class) which will log messages according to the specified logging level

  • Currently log messages are output through: Console and to a .log file.

Logging Levels

  • SEVERE : Critical problem detected which may possibly cause the termination of the application

  • WARNING : Can continue, but with caution

  • INFO : Information showing the noteworthy actions by the App

  • FINE : Details that is not usually noteworthy but may be useful in debugging e.g. print the actual list instead of just its size

4.7. Configuration

Certain properties of the application can be controlled (e.g App name, logging level) through the configuration file (default: config.json).

5. Documentation

We use asciidoc for writing documentation.

ℹ️
 We chose asciidoc over Markdown because asciidoc, although a bit more complex than Markdown, provides more flexibility in formatting.

5.1. Editing Documentation

See UsingGradle.adoc to learn how to render .adoc files locally to preview the end result of your edits. Alternatively, you can download the AsciiDoc plugin for IntelliJ, which allows you to preview the changes you have made to your .adoc files in real-time.

5.2. Publishing Documentation

See UsingTravis.adoc to learn how to deploy GitHub Pages using Travis.

5.3. Converting Documentation to PDF format

We use Google Chrome for converting documentation to PDF format, as Chrome’s PDF engine preserves hyperlinks used in webpages.

Here are the steps to convert the project documentation files to PDF format.

  1. Follow the instructions in UsingGradle.adoc to convert the AsciiDoc files in the docs/ directory to HTML format.

  2. Go to your generated HTML files in the build/docs folder, right click on them and select Open with → Google Chrome.

  3. Within Chrome, click on the Print option in Chrome’s menu.

  4. Set the destination to Save as PDF, then click Save to save a copy of the file in PDF format. For best results, use the settings indicated in the screenshot below.

chrome save as pdf
Figure 19. Saving documentation as PDF files in Chrome

5.4. Site-wide Documentation Settings

The build.gradle file specifies some project-specific asciidoc attributes which affects how all documentation files within this project are rendered.

💡
 Attributes left unset in the build.gradle file will use their default value, if any.
Table 1. List of site-wide attributes
Attribute name Description Default value

site-name

The name of the website. If set, the name will be displayed near the top of the page.

not set

site-githuburl

URL to the site’s repository on GitHub. Setting this will add a "View on GitHub" link in the navigation bar.

not set

site-seedu

Define this attribute if the project is an official SE-EDU project. This will render the SE-EDU navigation bar at the top of the page, and add some SE-EDU-specific navigation items.

not set

5.5. Per-file Documentation Settings

Each .adoc file may also specify some file-specific asciidoc attributes which affects how the file is rendered.

Asciidoctor’s built-in attributes may be specified and used as well.

💡
 Attributes left unset in .adoc files will use their default value, if any.
Table 2. List of per-file attributes, excluding Asciidoctor’s built-in attributes
Attribute name Description Default value

site-section

Site section that the document belongs to. This will cause the associated item in the navigation bar to be highlighted. One of: UserGuide, DeveloperGuide, LearningOutcomes*, AboutUs, ContactUs

* Official SE-EDU projects only

not set

no-site-header

Set this attribute to remove the site navigation bar.

not set

5.6. Site Template

The files in docs/stylesheets are the CSS stylesheets of the site. You can modify them to change some properties of the site’s design.

The files in docs/templates controls the rendering of .adoc files into HTML5. These template files are written in a mixture of Ruby and Slim.

⚠️

Modifying the template files in docs/templates requires some knowledge and experience with Ruby and Asciidoctor’s API. You should only modify them if you need greater control over the site’s layout than what stylesheets can provide. The SE-EDU team does not provide support for modified template files.

6. Testing

6.1. Running Tests

There are three ways to run tests.

💡
 The most reliable way to run tests is the 3rd one. The first two methods might fail some GUI tests due to platform/resolution-specific idiosyncrasies.

Method 1: Using IntelliJ JUnit test runner

  • To run all tests, right-click on the src/test/java folder and choose Run 'All Tests'

  • To run a subset of tests, you can right-click on a test package, test class, or a test and choose Run 'ABC'

Method 2: Using Gradle

  • Open a console and run the command gradlew clean allTests (Mac/Linux: ./gradlew clean allTests)

ℹ️
 See UsingGradle.adoc for more info on how to run tests using Gradle.

Method 3: Using Gradle (headless)

Thanks to the TestFX library we use, our GUI tests can be run in the headless mode. In the headless mode, GUI tests do not show up on the screen. That means the developer can do other things on the Computer while the tests are running.

To run tests in headless mode, open a console and run the command gradlew clean headless allTests (Mac/Linux: ./gradlew clean headless allTests)

6.2. Types of tests

We have two types of tests:

  1. GUI Tests - These are tests involving the GUI. They include,

    1. System Tests that test the entire App by simulating user actions on the GUI. These are in the systemtests package.

    2. Unit tests that test the individual components. These are in seedu.address.ui package.

  2. Non-GUI Tests - These are tests not involving the GUI. They include,

    1. Unit tests targeting the lowest level methods/classes.
      e.g. seedu.address.commons.StringUtilTest

    2. Integration tests that are checking the integration of multiple code units (those code units are assumed to be working).
      e.g. seedu.address.storage.StorageManagerTest

    3. Hybrids of unit and integration tests. These test are checking multiple code units as well as how the are connected together.
      e.g. seedu.address.logic.LogicManagerTest

6.3. Troubleshooting Testing

Problem: HelpWindowTest fails with a NullPointerException.

  • Reason: One of its dependencies, HelpWindow.html in src/main/resources/docs is missing.

  • Solution: Execute Gradle task processResources.

7. Dev Ops

7.1. Build Automation

See UsingGradle.adoc to learn how to use Gradle for build automation.

7.2. Continuous Integration

We use Travis CI and AppVeyor to perform Continuous Integration on our projects. See UsingTravis.adoc and UsingAppVeyor.adoc for more details.

7.3. Coverage Reporting

We use Coveralls to track the code coverage of our projects. See UsingCoveralls.adoc for more details.

7.4. Documentation Previews

When a pull request has changes to asciidoc files, you can use Netlify to see a preview of how the HTML version of those asciidoc files will look like when the pull request is merged. See UsingNetlify.adoc for more details.

7.5. Making a Release

Here are the steps to create a new release.

  1. Update the version number in MainApp.java.

  2. Generate a JAR file using Gradle.

  3. Tag the repo with the version number. e.g. v0.1

  4. Create a new release using GitHub and upload the JAR file you created.

7.6. Managing Dependencies

A project often depends on third-party libraries. For example, Address Book depends on the Jackson library for XML parsing. Managing these dependencies can be automated using Gradle. For example, Gradle can download the dependencies automatically, which is better than these alternatives.
a. Include those libraries in the repo (this bloats the repo size)
b. Require developers to download those libraries manually (this creates extra work for developers)

Appendix A: Product Scope

Target user profile:

  • SoC students with work/project experience/CS skills who are applying for programmes/ internships/jobs/etc

Value proposition:

  • Easy to use: CLI makes things fast and simple

  • Flexible: Able to customise resume for specific job requirements

  • SOC-aware: Save time with built in support for School of Computing programmes

Appendix B: 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

Save pieces of information about my relevant experience

Generate resumes without having to type the same things every time

* * *

Student

Generate a resume with only information relevant to a particular field of CS

Conveniently customise my resume for different applications.

* * *

Student

Have my Work Experiences and Projects sorted by relevance to job requirements, on my resume

Ensure my resume is relevant to the employer

* * *

Student

Search for entries using filters

Check my saved entries conveniently

* * *

Student

Generate resumes in common file formats like PDF

My resumes are accepted by everyone

* * *

Student

Update or delete my personal information conveniently

Ensure that the resumes the tool generates are up to date

* * *

Student

Have my contact information and other “standard” information automatically added to my resumes

Focus on crafting the more valuable information in my resume

* *

Student

Save custom combinations of tags

Filter the exact entries I want to be put in my resume

* *

Student

Receive feedback from my CLI commands

Be sure of the results of my commands

* *

SoC Student

My resume to automatically contain descriptions of common SOC programmes (Orbital, NOC, etc)

Save time instead of having to input standard information manually

* *

SoC Student

Pick standard SOC awards (Honour Roll, etc) from a list rather than type them out manually

Save time instead of having to input standard information manually

* *

Student

Have common NUS acronyms auto-translated into their full forms

So that I may type information using acronyms conveniently

* *

Student with existing work

Import my existing projects from Github

Save time typing them out manually

*

Student with multiple computers

Export my saved information and import it on another computer

Generate resumes wherever I go

*

Student

Undo commands and revert any changes made

Quickly recover from making a typo

*

Student

Easily learn how to use the tool from a built-in tutorial

Get started and work more efficiently

*

Student

Auto-fill information about special SoC programs

Saves the effect to input it by myself

*

Student

Conveniently contact people I have worked with in the past

Request testimonials or keep in touch for networking purposes

{More to be added}

Appendix C: Use Cases

(For all use cases below, the System is ResuMaker and the Actor is the Student, unless specified otherwise)

Add Personal Information of the user

MSS

  1. User enters command to set his contact details

  2. System prompts user for his mobile number, email address and GitHub username

  3. User enters in his contact information

  4. System prompts user for a confirmation

  5. User confirms his data

  6. System saves contact information

    Use case ends.

Extensions

  • 3a. User enters invalid personal information

    • 3a1. System prompts user to enter valid contact information

      Step 3 repeats as many times as necessary

Add a generic entry or major entry in the resuMaker

MSS

  1. User enters command to create a genric entry ( Skills / Awards), or major entry (Experience / Education)

  2. System saves the Entry to the disk

    Use case ends.

Delete an Entry under a specific category

MSS

  1. User filter the entries using specific tags, returning an indexed list of entries (UC04)

  2. User delete the corresponding entries in the list by indicating associated index for each entry to be deleted

  3. System saves the Entry to the disk

    Use case ends.

Extensions

  • *a. User input command using the wrong syntax

    • *a1. System prompts the user to re-enter the command

    • *a2. User re-enters the command

  • 3a. User inputs an index out of range

    • 3a.1 System prompts for invalid input and asks user to re-enter the command

    • 3a.2 return to step 4 for the user to re-enter the command

edit an Entry under a specific index

MSS

  1. User searches for a set of Entries, using some tags (UC04)

  2. System displays an indexed list of Entries matching the search tags (UC04)

  3. User enters command to edit Entries, and specifies an index and also the updated information

  4. System displays the updated Entry for reference

  5. System saves the Entry to the disk

    Use case ends.

Extensions

  • *a. User input command using the wrong syntax

    • *a1. System prompts the user to re-enter the command

    • *a2. User re-enters the command

  • 3a. User inputs an index out of range

    • 3a.1 System prompts for invalid input and asks user to re-enter the command

    • 3a.2 return to step 4 for the user to re-enter the command

Add information about a SoC / NUS Event (e.g. Hack N Roll, Student Exchange, Independent Work module)

MSS

  1. User enters command to create new project, together with the “nus” keyword and the name of his Event

  2. System recognises the name of the Event, as well as its type (Project, Work Experience, Skill, etc)

  3. System prompts user to fill in further details of his Event, but also pre-fills some fields (such as duration, nature of Event)

  4. User finalises the Event details

  5. System prompts user to tag the Event, but also pre-selects some tags

  6. User finalises the tags applicable to the Event

  7. System saves the Event as an Entry

    Use case ends.

Extensions

  • 1a. User enters slang or an acronym instead of the full name of his Event (e.g. "ug research opps" instead of Undergraduate Research Opportunites Programme)

    • 1a1. System matches the slang / acronym to the full Event name in the database, if possible.

      Use case continues from Step 2.

  • 2a. System does not recognises the Project as a SOC project

    • 2a1. System informs the User that no default information is available, and all information must be entered manually (UC09)

      Use case ends.

Add an SoC Award entry

MSS

  1. User enters command to view list of SOC Awards

  2. System displays an indexed list of SOC Awards

  3. User selects a particular SOC Award by specifying its index.

  4. System prompts user to enter further details about the SOC Award (e.g. year)

  5. User completes data entry

  6. System saves the Award entry

    Use case ends.

Extensions

  • 3a. User does not find his award in the list

    • 3a1. User enters command to manually create an Award entry.

      Use case ends.

View a template

MSS

  1. User enters command to view desired template using its filename

  2. System displays contents of the config

  3. User continues using the system

    Use case ends.

Extensions * 2a. Entered config name does not match any existing config.

+

  • 2a1. System displays a warning.

    Use case returns to Step 1.

Adding tag to an entry

MSS

  1. User enters command to list entries

  2. User enters command to add tag to entry

  3. System displays the entry with updated tags.

Extensions

  • 1a. User wants to check existing tags first to ensure new tag is not duplicate

    • 1a1. User enters commands to view list of tags and its corresponding entries

  • 3a. User decides not to create new tag

    • 3a1. User enters command to remove tag from entry

    • 3a2. System display entry with updated tags. Use case ends.

  • 4a. New tag is a duplicate of an existing tag

    • 4a1. System ignores duplicated tag

    • 4a2. System displays entry with updated tags

      Use case ends.

Viewing all active tags in resume generation

MSS

  1. User enters command to list all tags

  2. System displays all active tags and their entries' placement in the resume.

Filtering out entries of a specific tag

MSS

  1. User enters command to list all entries containing a specific tag.

  2. System displays all selected tags and their corresponding entries.

Extensions

  • 1a. No entries found for tag specified by user

    • 1a1. System outputs an empty list

Retagging tags of a specific entry.

MSS

  1. User enters command to retag a specific entry.

  2. System displays all selected tags and their corresponding entries.

Extensions

  • 1a. No entries with the specified index

    • 1a1. System displays an error message to alert user erroneous input.

Removing tags from a specific entry.

MSS

  1. User enters command to remove all tags from specific entry.

  2. System displays selected entry void of tags.

Extensions

  • 1a. No entries with the specified index

    • 1a1. System displays an error message to alert user erroneous input.

Generate a resume

MSS

  1. Student enters command to create resume and specifies a template file, by providing the file path to the template file

  2. System saves a markdown file containing a resume based on the template and the entries specified by the template

    Use case ends.

Extensions

  • 1a. User does not specify a template file

    • 1a1. System uses a pre-defined default template file instead

      Use case resumes from Step 2.

  • 1b. User specifies a template file using an alias instead of a filepath

    • 1b1. System reads application settings to match the file’s alias with its filepath

      Use case resumes from Step 2.

Appendix D: Non Functional Requirements

  1. Should work on any mainstream OS as long as it has Java 9 or higher installed.

  2. A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.

  3. The primary mode of input should be a Command Line Interface.

  4. All application data must be stored locally, and in a human editable file

  5. There should be no installer for the application.

  6. Resume generation should be fast (within 2 minutes).

Appendix E: Glossary

Mainstream OS

Windows, Linux, Unix, OS-X

Entry

Contact, Education, Work Experience, Project, Skill or Award

Event

Work Experience, Project, or Award

Work Experience

Any professional work (internship, freelance, job)

Project

Any work done by student outside school/work requirements

Skill

Proficiency in any language / framework / tool relevant to Computer Science professionals

Award

Any award / recognition

Contact

Student’s email address, mobile phone number and GitHub Profile

Education

University name, degree programme name, Year of Study

Standard Information

Student’s Contact and Education Details

Template

Sets of tags for each Section of a resume - to be used to custom generate a resume

Template File

A plaintext file containing a Template

Category

A single-word keyword starting with ~ (e.g. ~work, ~project)

Tag

A single-word keyword starting with #

Slang

A single word that is an alias for a full phrase. (e.g. cs is slang for computer science)

Partial phrase

An incomplete word. (e.g. comp)

Full phrase

Single or multiple complete words. (e.g. computer, computer science)

Expression

A combination of slang, partial phrases or full phrases. (e.g. 'computer sci ug research proj')
In Backus-Naur form, an Expression is defined:
<expression> ::= <slang> | <partial-phrase> | <full-phrase> | <expression>

Entry Management

A set of features related to managing entries. Namely: addEntry, deleteEntry, addBullet, deleteBullet.

major entry

An entry that contains information such as title, subtitle and duration. It is usually used for education, professional experience, projects, etc. For example, to add a particular major entry, execute addEntry ~work #java t/The Source Enterprise s/Java Programmer intern d/ May 2010 - Aug 2010.

minor entry

An entry that does not contain entry information such as title, subtitle and duration. It is usually created for content like awards or certification. For example, to add a particular minor entry, one can execute addEntry ~awards #java

Appendix F: Product Survey

Product Name

Author: …​

Pros:

  • …​

  • …​

Cons:

  • …​

  • …​

Appendix G: 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 requested to perform more exploratory testing.

G.1. 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 no resume entries. 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.

G.2. Add a resume entry

  1. Adding a resume entry via addEntry

    1. Test case: addEntry ~work #python #data t/DataKinetics Corp s/Dashboard visualisation expert d/May 2010 - August 2015
      Expected: First resume entry is added to the list of entries. Details of the added entry shown in the status message. Timestamp in the status bar is updated.

    2. Test case: addEntry ~work #python #data t/DataKinetics Corp s/Dashboard visualisation expert d/May 2010 - August 2015
      Expected: No entry is created. The status message indicates that this entry already exists.

    3. Other incorrect delete commands to try: add, add x (where x is missing some arguments)
      Expected: Similar to previous.

  2. Adding a resume entry via nus

    1. Test case: nus ta ma1101r
      Expected: Similar to the addEntry positive test case.

    2. Test case: nus teaching asst ma1101r
      Expected: Similar to the addEntry duplicate entry test case.

G.3. Saving data

  1. Dealing with missing/corrupted data files

    1. {explain how to simulate a missing/corrupted file and the expected behavior}

{ more test cases …​ }