Documentation changes

README.adoc

@@ -16,7 +16,7 @@ image::images/Ui.png[width="600"]
 endif::[]
 
 ****
-We’re hardworking studious students who want only the best-quality software for our learning. And we’re always on the go to achieve that perfect 5.0. That’s why we created KeyboardFlashCards: a highly efficient flashcard manager catered to the fastest typists, saving time for the optimal learning experience.
+We are a team of hardworking and studious students who want only the best-quality software for our learning. And we’re always on the go to achieve that perfect 5.0. That’s why we created _KeyboardFlashCards_: a highly efficient flashcard manager catered to the fastest typists, saving time for the optimal learning experience.
 ****
 * This is a desktop Flashcard management application. It has a GUI but most of the user interactions happen using a CLI (Command Line Interface).
 * It is developed mainly to assist students in learning and preparing for examinations.
@@ -33,6 +33,6 @@ We’re hardworking studious students who want only the best-quality software fo
 * AddressBook-Level3 project created by SE-EDU initiative at https://se-education.org
 * Some parts of this sample application were inspired by the excellent http://code.makery.ch/library/javafx-8-tutorial/[Java FX tutorial] by
 _Marco Jakob_.
-* Libraries used: https://openjfx.io/[JavaFX], https://github.com/FasterXML/jackson[Jackson], https://github.com/junit-team/junit5[JUnit5]
+* Libraries used: https://openjfx.io/[JavaFX], https://github.com/FasterXML/jackson[Jackson], https://github.com/junit-team/junit5[JUnit5], https://poi.apache.org/[Apache POI], https://github.com/google/gson[Google Gson]
 
 == Licence : link:LICENSE[MIT]

docs/AboutUs.adoc

@@ -4,8 +4,7 @@
 :imagesDir: images
 :stylesDir: stylesheets
 
-AddressBook - Level 3 was developed by the https://se-edu.github.io/docs/Team.html[se-edu] team. +
-_{The dummy content given below serves as a placeholder to be used by future forks of the project.}_ +
+_KeyboardFlashCards_ was developed by the https://github.com/AY1920S1-CS2103T-T12-4[AY1920S1-CS2103T-T12-4] team. +
 {empty} +
 We are a team based in the http://www.comp.nus.edu.sg[School of Computing, National University of Singapore].
 

docs/DeveloperGuide.adoc

@@ -283,10 +283,16 @@ prefixes like `t>` and `d>`
 // tag::flashcardexportimport[]
 
 === Exporting/Importing of FlashCards
+
+==== About
+
+Our application currently supports the exporting of `FlashCards` to two file formats ('.docx' and '.json'), and importing of `FlashCards` from one
+file format ('.json'). Through these features, a user can easily transfer their _KFC_ data to an external file, and another user
+can just as easily transfer the same data back into their own copy of _KFC_.
+
 ==== Implementation
 
-Our application currently supports the exporting of `FlashCards` to two file formats (`.docx` and `.json`) and importing of `FlashCards` from one
-file format (`.json`). These mechanisms are primarily facilitated by the following classes:
+The Export/Import feature is primarily facilitated by the following classes:
 
 * `ExportCommand` -- Embodies an `export` command by the user; carries information about which `FlashCards` are to be exported, and to where
 * `ExportCommandParser` -- Parses user input and uses it to construct an `ExportCommand` instance
@@ -307,66 +313,45 @@ Once created, an `ExportPath` will expose the following relevant methods:
 * `export(List<FlashCard> list)` -- Exports the given `List` of `FlashCards` to the file path embodied by this `ExportPath`
 * `importFrom()` -- Attempts to import `FlashCards` from the file path represented by this `ExportPath`
 
-CAUTION: Not all `ExportPath` subclasses will implement the `importFrom()` method. `DocumentPath`, for example, does not - this is because documents are
-relatively unstructured and impractical to import from, and there are other reasons for exporting to a document (e.g. to use as cheat sheet).
+CAUTION: Not all `ExportPath` subclasses will implement the `importFrom()` method. `DocumentPath`, for example, does not.
 
 Because `ExportPath` follows the factory pattern, any class that deals with `ExportPath` or its subclasses need not know which particular subclass it is
 dealing with exactly. Each `ExportPath` subclass will implement its own `export` and `import` methods, which, when called, will perform the required operations
 without any further hassle. Of course, due to the Separation of Concerns principle, the `ExportPath` subclasses will not handle these directly.
 Instead, they will delegate the work to other utility classes, which, in turn, interface with the external libraries necessary to complete the task.
 
-TIP: The exporting/importing functionality is extremely easy to extend - support for new formats can be added simply through the creation of new subclasses of `ExportPath`.
+TIP: The exporting/importing functionality is extremely easy to extend - you can add support for a new format simply through the creation of new subclasses of `ExportPath`.
 
-NOTE: All relevant classes can be found in the `seedu.address.model.export` package. The only exceptions are `ExportCommand`, `ImportCommand`, `ExportCommandParser`, and `ImportCommandParser`, which can be found in the `seedu.address.logic` package.
+NOTE: You can find all relevant classes in the `seedu.address.model.export` package. The only exceptions are `ExportCommand`, `ImportCommand`, `ExportCommandParser`, and `ImportCommandParser`, which can be found in the `seedu.address.logic` package.
 
 The following table shows the classes and methods that you may have to deal with when exporting to or importing from each format:
 
-[width="59%",cols="20%,35%,35%",options="header",]
-|====
-
-|**File format**                        |Document           |JSON
-
-|**File extension**                     |`.docx`            |`.json`
-
-|**`ExportPath` subclass**              |`DocumentPath`     |`JsonExportPath`
-
-a|**Export utility class and method**
-a|`DocumentExportUtil#exportFlashCardsToDocument( List<FlashCard>, DocumentPath)`
-a|`JsonExportUtil#exportFlashCardsToJson( List<FlashCard>, JsonExportPath)`
+image::ExportDgTable.png[width="75%"]
 
-a|**Import utility class and method**
-a|_None - importing not supported_
-a|`JsonImportUtil#importFlashCardsFromJson( JsonExportPath)`
+_Table 1: Overview of classes and methods involved in the Export/Import feature_
 
-|**External library used**              |Apache POI         |Jackson
-|====
-
-The number of classes supporting the import/export feature is rather large. The following class diagram will help to clarify the associations
+The number of classes supporting the Export/Import feature is rather large. These classes also span more than one
+package in the application. The following class diagram will help you to better understand the associations and relationships
 between these classes:
 
-image::ExportClassDiagram.png[height="600"]
+image::ExportClassDiagram.png[]
 
-_Figure 1: Class diagram showing the classes directly relevant to importing and exporting_
+_Figure 1: Class diagram of the classes directly relevant to importing and exporting_
 
-The following sequence diagram shows how the export operation works when the user tries to export to a document (`.docx`) file:
+The following sequence diagram shows the classes, methods, and interactions involved
+when the user tries to `export` to a document file:
 
-image::ExportSequenceDiagram.png[width = "600"]
+image::ExportSequenceDiagram.png[]
 
 _Figure 2: Sequence diagram showing the process of exporting to a document file_
 
-NOTE: Due to a limitation of PlantUML, object lifelines in the diagram extend beyond the destroy markers. This, of course, should be ignored.
-
-The following activity diagram summarizes what happens when a user executes an export command:
-
-image::ExportActivityDiagram.png[width="300"]
+The following activity diagrams provide a general overview of the events that occur when a user executes an `export` or `import` command:
 
-_Figure 3: Activity diagram of when the user executes an export command_
+image:ExportActivityDiagram.png[width=440,height=518]
+image:ImportActivityDiagram.png[width=383,height=513]
 
-The following activity diagram summarizes what happens when a user executes an import command:
-
-image::ImportActivityDiagram.png[width="300"]
-
-_Figure 4: Activity diagram of when the user executes an import command_
+_Left - Figure 3: Activity diagram of the execution of an `export` command_ +
+_Right - Figure 4: Activity diagram of the execution of an `import` command_
 
 ==== Design considerations
 
@@ -389,33 +374,13 @@ NOTE: **Alternative 1** was preferred for its ease of extensibility.
 
 * **Alternative 1:** Update the `Model` to show all desired `FlashCards`, then export all of said `FlashCards`
 ** Pros: Is easy to implement as it makes use of existing logic in `Model`; user receives immediate visual feedback regarding which specific `FlashCards` were exported
-** Cons: May cause confusion - `export` command does not imply that the selected `FlashCards` will also be shown to the user
+** Cons: May cause confusion - name of `export` command does not imply that the selected `FlashCards` will also be shown to the user
 * **Alternative 2 (current choice):** Implement a new method in `Model` that returns the selected `FlashCards`, without updating the on-screen list
 ** Pros: Will not cause confusion to user - `export` command does exactly what one would expect it to do
 ** Cons: Is harder to implement and might result in duplication of logic
 
 NOTE: **Alternative 2** was preferred as it provides users with an experience closer to what they would expect.
 
-===== Aspect: Parsing of file path from user input
-
-NOTE: The original AddressBook application, from which KeyboardFlashCards was morphed, delimited its command arguments using slash-containing flags
-(e.g. `c/CATEGORY`). This sometimes caused parsing problems due to the nature of file paths, which likewise contain slashes.
-
-* **Alternative 1:** Read file path as-is, using the existing AddressBook parser
-** Pros: Does not require further code changes
-** Cons: Means that errors may occur for certain file paths
-* **Alternative 2:** Disallow user from selecting file path - instead, always export to and import from a specific directory
-** Pros: Is somewhat easy to implement
-** Cons: Requires user to navigate to the specified directory; requires a means of finding alternatives if the default directory does not exist
-* **Alternative 3:** Ask user to replace slashes in file path with another character
-** Pros: Is very easy to implement
-** Cons: Greatly inconveniences the user; extra work must be done to restore the input to the original file path
-* **Alternative 4 (current choice):** Overhaul the AddressBook parser to use `>` rather than `/` as a delimiter
-** Pros: Provides the user with the most power and convenience
-** Cons: Might possibly break existing functional and test code; may require an additional button press from the user (`Shift`) in order to type `>`
-
-NOTE: **Alternative 4** was preferred as it provides users with the greatest overall convenience.
-
 // end::flashcardexportimport[]
 
 //@@author keiteo

docs/UserGuide.adoc

@@ -29,6 +29,14 @@ can help you manage your flashcards much more efficiently than traditional GUI a
 Interested? You should be! KFC is perfect for NUS Computing students. We even have additional
 features not available with most flashcard managers that we're sure you'll love. Enjoy!
 
+Please also note the following icons, which will indicate points of interest throughout this document.
+
+NOTE: A point of information that you may wish to note
+
+TIP: A tip or suggestion
+
+CAUTION: A cautionary word of advice
+
 == Quick Start
 
 .  Ensure you have Java 11 or above installed in your Computer.
@@ -39,7 +47,6 @@ features not available with most flashcard managers that we're sure you'll love.
 .Graphical User Interface of KeyboardFlashCards[
 image::annotatedUi.png[width="790"]
 
-<<<
 //tag::features[]
 
 == Features
@@ -56,15 +63,6 @@ This section contains the features and their respective commands.
 ====
 //end::features[]
 
-Please also note the following icons, which will indicate points of interest throughout this document.
-
-NOTE: A point of information that you may wish to note
-
-TIP: A tip or suggestion
-
-WARNING: A cautionary word of advice
-
-<<<
 //tag::flashcardAll[]
 //tag::flashcard[]
 === Add new FlashCard: `add q>QUESTION a>ANSWER [c>CATEGORY]...`
@@ -355,7 +353,7 @@ You can stop the test any time simply by typing `end`.
 You can use this command to export all your FlashCards in a particular category, to an external file.
 This may be useful if you wish to publish your FlashCards somewhere, print them out, or share them with a friend.
 The file will be located at the file path that you specify, and the format of the file will be inferred from the
-extension. We currently support exporting to JSON (.json) and document (.docx) file formats. +
+extension. We currently support exporting to JSON ('.json') and document ('.docx') file formats. +
 Example: `export c>CS2105 p>C:\Documents\cs2105.json`
 
 Suppose you have a category named `CS2105`, and you wanted to export the FlashCards in that category to an external file
@@ -369,19 +367,27 @@ image::ExportDemo1.png[width="600"]
 +
 image::ExportDemo2.png[width="600"]
 
-. Navigate to the directory that you specified in the command (in this case, it would be 'C:\Documents'). Sure enough, your exported file is there!
+. Using your file explorer, navigate to the directory that you specified in the command (in this case, it would be `C:\Documents`). Sure enough, your exported file is there!
 +
 image::ExportDemo3.png[width="600"]
 
-NOTE: Only the questions and answers of FlashCards will be exported.
+Please refer to the table below for a summary of the file formats that we support exporting to:
 
-CAUTION: Your file paths must be comprised solely of alphanumeric characters, spaces, and the following characters: `~\/-_!:[]()` +
-It must also end in either `.json` or `.docx`.
+|====
+|**Format**|Document ('.docx')|JSON ('.json')
+|**Intended purpose**|For use as a cheat sheet|For sharing
+|**What is copied from each FlashCard**|Question and answer only|Question, answer, and the category which you specified in the export command
+|====
 
-CAUTION: Do note that some directories may be protected by your operating system (`C:\` on Windows, `/` on Unix). You may not be allowed to save files to these directories.
+NOTE: If you're on a Unix-based operating system (e.g. Mac OS, Linux), any absolute paths that you specify will have to begin from the root directory `/`, not the user directory `~`. For example, if you were on a Mac and your username was "jason", and you wanted to export to a document file on your desktop, the file path would be `/Users/jason/Desktop/document.docx`.
+
+CAUTION: Your file paths must be comprised solely of alphanumeric characters, spaces, and the following characters: `~\/-_!:[]()` +
+It must also end in one of the supported file extensions - either `.json` or `.docx`. +
+{blank} +
+Do note that some directories may be protected by your operating system (`C:\` on Windows, `/` on Unix). You may not be allowed to save files to these directories. +
+{blank} +
+Please take care not to modify exported JSON files - your friends might have trouble importing them otherwise.
 
-TIP: Use this to export your flashcards into an easily-printable cheat sheet! Use them for your assessments or
-self-learning.
 
 // end::flashcardexport[]
 
@@ -392,10 +398,10 @@ self-learning.
 === Import flashcards from a JSON file: `import p>FILE_PATH`
 
 You can use this command to import FlashCards from a file that you or someone else had exported to earlier.
-We currently only support importing from JSON (.json) files. +
+We currently only support importing from JSON ('.json') files. +
 Example: `import p>C:\Downloads\cs2105.json`
 
-Suppose your friend has kindly exported some of his FlashCards for you to use. You have download the `.json` file that he sent you,
+Suppose that your friend has kindly exported some of his FlashCards for you to use. You have download the JSON file that he sent you,
 and it's currently located at the following path: `C:\Downloads\cs2105.json`.
 Your next step is to get those FlashCards into your copy of KFC. Here's how you'd go about this:
 
@@ -408,7 +414,7 @@ Furthermore, the category list on the left will now display the category of the
 +
 image::ImportDemo2.png[width="600"]
 
-NOTE: Duplicate FlashCards will not be imported. You will be notified when we detect duplicate FlashCards in the file you provide.
+NOTE: Duplicate FlashCards will not be imported. _KFC_ will notify you if it detects duplicate FlashCards in the provided file.
 
 // end::flashcardimport[]
 

docs/diagrams/ExportClassDiagram.puml

@@ -57,7 +57,7 @@ JsonImportUtil .. JsonExportPath
 
 
 
-ExportCommand "0..1" ------> "1" ExportPath LOGIC_COLOR
+ExportCommand "0..1" --> "1" ExportPath LOGIC_COLOR
 ImportCommand "0..1" --> "1" ExportPath LOGIC_COLOR
 
 ExportCommandParser .. ExportPath LOGIC_COLOR

docs/stylesheets/gh-pages.css

@@ -211,4 +211,8 @@ table.tableblock > .title,
     #site-header {
         display: none;
     }
+
+    a[href]:after {
+        content: none !important;
+    }
 }