Current:

The current tutorial is a chain of many steps going up to 28 steps. It is told in the form of narration from start to finish.

Problem

It becomes challenging to link each step during tracing to the sequence diagram.

Proposed

We can add headers to highlight which logic interaction is currently being traced, for example, when LogicManager passes control to AddressBookParser, we can explicitly mention this in header in whatever is the best form. It is hoped this can allow them to relate it to the introduced sequence diagram in high level overview in #16 easily

We can also highlight it in a diagram?

Add the tip mentioned in nus-cs2103-AY2223S1/forum#384 to the https://se-education.org/guides/tutorials/plantUml.html

Current:
Has 3 parts: echoing the user, adding dialog boxes, and adding custom behavior to dialog boxes.

Problem:
Lacking an introduction to even handlers in general. Students may lack a general understanding of event handlers, and may face difficulties when using event handlers for different controls.

Proposed:
Introduce the general logic for event handlers, some common event handlers for different controls, and a link to more advanced event handlers that are not likely to be used in the Duke project for exploration.

Current:

Problem:

1. The text says “ScrollPane” but the image shows scrollbar
2. The fact that ScrollPane is considered a Control maybe confusing to the students because it looks like a container and is also under “container” in Scene Builder although it extends Control class.
   Proposed:
3. Change the image for ScrollPane to the entire ScrollPane
4. Briefly explain to the students that “ScrollPane” actually extends the Control class although it seems like a container due to its interactive feature.

Current:

Debugger features introduction

Problem:

The use of the debugger features is relevant and crucial to the tutorial, but usage of these features are scattered with no explanation of what it means to show execution point, step into a method call, step over logging code or step out.

Proposed:

Include a section at the beginning to introduce features of the debugger and what they are used for.

Understanding Debugger Features

Before diving into tracing code with IntelliJ IDEA’s debugger, it’s essential to understand key debugger features and their purpose. These features help you step through code systematically, inspect variable values, and understand program flow during execution. Here are the primary debugger features you'll use:

Setting Breakpoints

Purpose: Breakpoints pause program execution at specific lines of code.
Usage: Place breakpoints at critical points where you want to examine the program state, such as method entry points or before complex operations.

Showing Execution Point

Purpose: Shows the current line of code where the debugger has paused execution.
Usage: Helps you navigate directly to the line where the program is halted, providing context for the next step.

Stepping Into a Method Call

Purpose: Steps into the implementation of a method called at the current execution point.
Usage: Useful for delving into how specific methods work, especially when you want to understand detailed functionality.

Stepping Over Code

Purpose: Executes the current line of code without stepping into method calls.
Usage: Used to skip over lines of code that are not critical for understanding the current flow, such as logging or simple getter/setter methods.

Stepping Out of a Method

Purpose: Executes the remaining lines of code in the current method and returns to the caller.
Usage: Useful when you've stepped into a method and want to quickly return to the higher-level context without stepping through every line.

Please have a look at the significantly-revamped Java FX tutorial here and report any problems or suggestions as separate issues in this issue tracker. If you found no issues, you can reply in this thread so that your effort doesn't go unnoticed.

Strongly suggested to follow the tutorial as if you are a student (i.e., actually do the steps given) so that we can tease out hidden issues.

As in the title. I suggest adding "don't hover the mouse over any link while saving as PDF" to https://se-education.org/guides/tutorials/savingPdf.html .

Reason: otherwise one of the link may look blackened and underlined like this.

I've added an empty VSCode guide at https://se-education.org/guides/tutorials/vscode.html

This page is supposed to provide helpful info for VSCode users, similar to what we have provided for Intellij.
However, VSCode is not supported officially by our courses, which means this guides will be an 'unofficial community resource'.
For the moment, let's keep it as one page, but we can split it into multiple pages later.

Feel free to send PRs to add content to this page, one section at a time. Perhaps best to post in this issue first to propose your content, to avoid PR overlap.

Current

Problem

Inconsistency in the alert/tip boxes. This can make readers confused or feel that the content is very messy.

Proposed

To standardise all tips (with the light bulbs) to be placed in the boxes. Certain tips can also be classified as “Note" or " Info" and be put in a different color box to avoid overwhelming the reader with too many tip boxes.

Note: This can be improved across all 3 tutorials.

Current:

Problem:

Label and ImageView is created in handleUserInput and passed to DialogBox, which may increase dependency and reduce readability of code.

Proposed:

Constructor of DialogBox can be something as below:

public DialogBox (String s, Image i) {
    text = new Label(s);
    displayPicture = new ImageView(i);
    // ...
}

handleUserInput can be something as below:

private void handleUserInput() {
    String userText = userInput.getText();
    String dukeText = getResponse(userInput.getText());
    dialogContainer.getChildren().addAll(
            new DialogBox(userText, user),
            new DialogBox(dukeText, duke)
    );
    userInput.clear();
}

Current

There is no common Debugging Tips/explanation section for new users

Problem

Instead of jumping around between web pages or sections, it would be helpful to have a consolidated debugging tips section filled with the most important information and tips for beginners.

For example: Beginners might not know the differences between step-in and step-over.

Proposed

Add a basic tips section that serves as a quick summary and refresher for students not used to the debugger.
This section will include tips about the debugger's different functionalities and usages.

Current

Problem

Currently, there is no/minimal spacing between images and text. This makes reading difficult for the student because the information is too cluttered.

Proposed

To increase the margins (e.g. 20px) between text and images. To increase the line height for text for better readability.

Current:

Problem:
Students might not know what to expect after setting a breakpoint at the first statement of the main method.

Proposed:
Insert the following paragraph at the end, to show the result of putting a breakpoint in the first statement of the main method:

Upon running the application with the breakpoint in the first statement of the main method, you will realize that the app is launched via this method.

Current:
"Styling" section only include those for containers and user input box. It also only gives instructions on styling to get the example UI, without much explanation.

Problem:
Styling for dialog box elements is not specifically mentioned. It is only mentioned later in part 3, but it is more relevant to part 2. Furthermore, this part does mention that readers should refer to the official JavaFX documentation for a comprehensive list of properties to modify. However, some students may not read them especially when they are given a ready-for-use piece of code for their individual project.

Proposed:
Also explore styling for Image View and text label.
Mentions some of the most commonly-used properties for each element as examples. For example, wrapping in text label and scroll panel and binding of width and height can be mentioned. Provide explanation for lines of code whose purposes are not immediately understandable.

Current:
ImageView and Label are shown as nodes in a VBox

Problem:
According to the mockup screenshot, the ImageView and Label are in a HBox which forms the DialogBox, and the DialogBoxes are stacked in a VBox as the content of the ScrollPane.
Proposed:
Under the "VBox" node, we should have:
HBox -> VBox
ImageView -> HBox
Label -> HBox

In Automating the testing of text UIs, the first sentence of Setting up is

Given below re steps to set it up for a project.

I believe "re" is a corruption of "are".

Description

I ran a scan of all the pages under https://se-education.org/guides/ using Linkinator with the following command:

npx linkinator http://se-education.org/guides/ --recurse --format JSON 

5 broken links were found below:

{
  "Date Generated": "24/01/2023 20:12",
  "URL List": [
    {
      "url": "https://mvnrepository.com/artifact/com.joestelmach/natty/0.6",
      "status": 403,
      "state": "BROKEN",
      "parent": "http://se-education.org/guides/tutorials/gradle.html"
    },
    {
      "url": "http://se-education.org/guides/conventions/index.page-vue-render.js",
      "status": 404,
      "state": "BROKEN",
      "parent": "http://se-education.org/guides/conventions/java"
    },
    {
      "url": "https://github.com/MarkBind/markbind/edit/master/.github/ISSUE_TEMPLATE/bug-report.md",
      "status": 404,
      "state": "BROKEN",
      "parent": "http://se-education.org/guides/conventions/github.html"
    },
    {
      "url": "https://mdn.beonex.com/en/CSS/Writing_Efficient_CSS.html",
      "status": 404,
      "state": "BROKEN",
      "parent": "http://se-education.org/guides/conventions/css.html"
    },
    {
      "url": "http://se.inf.ethz.ch/old/teaching/ss2007/251-0290-00/project/CSharpCodingStandards.pdf",
      "status": 404,
      "state": "BROKEN",
      "parent": "http://se-education.org/guides/conventions/csharp.html"
    }
  ]
}

Solution

The general steps to follow when solving this are as follows:

1. Verify if there are any false positives (Based on what I've looked at thus far, I think only the first finding is a false positive)
2. Find the context of the broken link (what is the original intention of the link etc)
3. Using the context, find a suitable substitute link

Current

Tutorial primarily focuses on a single "happy path" scenario.

Problem

Users may not be familiar with how exceptions are thrown and handled, particularly CommandException and ParseException. This lack of understanding could lead to confusion, especially in subsequent tutorials that involve adding commands and handling these exceptions.

Proposed Solution

Enhance the tutorial by including examples of CommandException and ParseException being thrown and traced. This will help users understand the flow of these exceptions and how to manage them effectively in their code. This can be added before the Conclusion which also has other examples of possibly problem user inputs.

Currently most online tutorials use a coding pack to download the JDK, extensions.
However, CS2103T uses Java 11, hence the versions may cause an issue via the automated install. which may install Java 17.
We can break this down into

1. Download JDK manually from Oracle
2. Download the extensions (may not include Gradle, as I was thinking of putting it in separate section)
3. Setup a main project (just for completion and running) using the VSCode java commands

Current

The page briefly introduces the remark command format as remark INDEX r/REMARK with a quick example.

Problem

For beginners or students who do not have a thorough understanding of the documents or architecture, the significance of INDEX and REMARK would not be immediately clear. They might not understand that INDEX refers to the position of the person in the address book list or how to format the REMARK text.

Proposed

Enhance the explanation of the command format with a quick explanation. For instance, explain that INDEX refers to the list position of the person you want to add a remark to, and REMARK is the note or comment you wish to attach to their entry.

Proposed changes:

remark INDEX r/REMARK
E.g.: remark 2 r/Likes baseball (adds the remark “Likes baseball” to the current person at index 2 of the observable list)

In the JavaFX guides, add this tip to the appropriate place
And this as well?

Current:

Problem:
Students might not understand what it means by “various event-driven mechanisms” and may be confused on the choice of placing the breakpoint where the UI transfer controls to the logic component.

Proposed:
Add a paragraph after the highlighted part:

This is because, unlike linear command-line programs, GUI applications respond to user actions (like clicks and keystrokes) and other events, triggering various event listeners and handlers. This non-linear flow of control can make it difficult to trace and debug the sequence of operations, as the program reacts dynamically to different events, creating an obscure execution path.

Current:
Uses a tree diagram to show the various nodes of the UI

Problem:
Does not reflect how this structure renders on the actual UI. May not be directly and immediately understandable.

Proposed:
Add a screenshot of the UI and label each component. Show the inclusion logic with the label.

Current:

Problem:

Text overrun may occur, and longer text will not be fully displayed but replaced with ellipsis instead.

Proposed:

Replace line with:

<Label fx:id="dialog" text="Label" wrapText="true" minHeight="-Infinity">

Current

The tutorial introduces a architecture diagram and a high level sequence diagram. Afterwards it links to a developer guide.

Problem

Students may be overwhelmed by the information in developer guide and hence may not retain much. They may also forego reading it at all.

Proposed

Instead of immediately directing students to the developer guide, start with a brief, guided overview of the essential component interactions. This overview will set the context for understanding the tracing code and make it easier for students to follow along.

Specifically,

• Discuss the lower-level sequence diagram, with the added UI component (attached image).

• We can retain the other integration of diagrams in the tracing code however.

Feedback appreciated thanks!

Fix these typos reported by past students, if still applicable

Typo in tutorial nus-cs2103-AY2324S2/forum#396
Typo in tutorial nus-cs2103-AY2324S2/forum#374
Typo in tutorial nus-cs2103-AY2324S2/forum#352
Typo in tutorial nus-cs2103-AY2324S2/forum#404
Typo in tutorial nus-cs2103-AY2324S2/forum#438

Current

Problem

This section is relevant and can be helpful for students to check on their understanding. However, as no answers are provided it falls short of allowing students to check their knowledge fully as they cannot verify whether their answers and path tracing are correct.

Proposed

Have a drop-down to reveal the answers for students to reference to, similar to the CS2103T website:

Current

Problem

It is mentioned that tracing using a debugger would be useful in understanding an unfamiliar codebase, but not why or how it helps.
The current tutorial does not give the background context on why tracing execution paths is important, how it helps and an overview of the tutorial. This might leave beginners who do not know what a debugger is or those unfamiliar with the concept of code tracing to feel lost.

Proposed

Add a detailed introduction that explains the importance of tracing code and what the reader can expect to learn.

## Introduction
Understanding the execution path of a program is crucial for debugging and extending existing codebases. Tracing code helps in identifying how different components interact, where potential bugs may occur, and how changes in one part of the code can affect the entire application. By the end of this tutorial, you will be equipped with the skills to: 
* Set breakpoints effectively.
* Trace the flow of execution through various components.
* Understand the interactions between different parts of the application. 
* Identify and troubleshoot issues within the code.

Current

Given that this resource is shorter and also mostly done as a read-through, it might be helpful to have additional resources.

Problem

Once beginners complete the tutorial, they might be interested in learning more about refactoring techniques, IntelliJ IDEA, or other related topics to improve their skills. With additional suggested resources for further reading, we can provide them with a launchpad for them to further explore on their own.

Proposed

Include a section on additional resources and further reading. Provide links to official IntelliJ IDEA documentation on refactoring tools, articles on refactoring best practices, and tutorials on advanced refactoring techniques.

It would be nice if there are intuitive directives to prompt the user to navigate to the next or previous page of a multi-page guide. For example, the JavaFX tutorial has 4 parts across 4 pages. Without the directives, some users might not be aware of other parts. Here is a sketch of what can be done:

On MacOS, preferences has been changed to settings. this is one instance in the guide where it appears wrongly @damithc should we update this for all the guides?

https://se-education.org/guides/tutorials/checkstyle.html

Create a brief guide to help users install the JDK, set up environment variables, and verify their installation across different operating systems.

We can add VSCode instructions with HTML tabs to supplement current existing IntelliJ instructions.

Update the JavaFX guide to capture the tip given in nus-cs2103-AY2324S1/forum#111, if applicable

Current:

Problem:

The tutorial states to check Use fx:root construct but does not explain what it does.

Proposed:

Insert a link to the JavaFX-FXML documentation on what is fx:root and add the following:
Checking this enables the use of the fx:root element, allowing you to reference a predefined root element. More about fx:root on the documentation Introduction to FXML | JavaFX 2.2 (oracle.com).

The page can be structured similar to https://se-education.org/guides/tutorials/javaInstallationMac.html
While installation itself is rather easy, some students might not know how to configure their system to be able to run java and javac commands, how to switch between Java versions etc.
Note that this guide is used by students of different courses, some of whom could be first-time Java users.

The current version does not allow scrolling if the ScrollPane is unselected unless the scrollbar is clicked. Note that the code is referenced from part 4 of the guide.

Using ChatGPT, I find that this fix works by changing the way we automatically scroll to the bottom, but I do not fully understand why the initial version will cause the above issue.

MainWindow.java:

    @FXML
    public void initialize() {
        //scrollPane.vvalueProperty().bind(dialogContainer.heightProperty());
        dialogContainer.heightProperty().addListener((observable, oldValue, newValue) -> scrollPane.setVvalue(1.0));
    }

Current:

Problem:
The code does not echo the tree diagram as there are no dialog boxes in the scroll pane. For the students to also learn about Vbox, Labels and Image View, instead of doing it later in this tutorial, this part of the code can include a sample dialog box.

Proposed:
Add in a temporary sample dialog box with image view and text label.