Overly complicated sequence diagram with incorrect command in caption

[teikjun]

Bug Description

There is an overly complicated sequence diagram in DG. The team may consider abstracting away less important information from the diagram, so that the reading developer can focus on the important ideas.

The caption states that the sequence diagram is "for the input opne /a". there is no such command shown in the guides. This can affect understanding for new developers taking over the project.

[nus-pe-bot]

Team's Response

I believe that while this is slightly longer, I should not leave out crucial steps in my sequence diagram. I have abstracted out less important methods such that the steps shown here are the crucial methods I MUST show to create a coherent sequence diagram. I have also checked with the Prof as my opinion may be subjective. However, the Prof said he did not find this confusing and allowed me to reject this bug.

Regarding the input "opne /a", I wanna show how the Suggestion Engine interacts with the Correction Engine to corrects the word "opne" to "open", while "/a" is just the input argument. I believe that this is an important aspect that I must show in my sequence diagram (instead of using the correct command "open") to show how our engines interact with each other. You may want to read our UG and DG again to check why our app allows the command "opne" to be executed.

Items for the Tester to Verify

❓ Issue response

Team chose [response.Rejected]

• I disagree

Reason for disagreement: I don't think you have fairly reflected the concerns regarding the bug report to the Prof. Also, I think he wasn't able to look into this issue carefully as the teaching team had a lot of work and emails to respond to after the PE. I think it may be difficult to read through everything carefully when you send a long email filled with diagrams and your justifications during a busy period.

I believe that the diagram presented is overly complex because:

1. It does not abstract out the important parts for the reader, adding more confusion than clarity
2. The fonts are too small and have poor contrast in comparison with the rest of the DG. It is difficult to read even when the user zooms into the diagram.
3. CorrectionEngine is part of the Logic Component, but it is shown the same color as the Model Component, and it is displayed outside of the Logic component box.

Not only that, many diagrams in the DG are overly complex, and does not convey the key information clearly to the reader. Instead, everything is dumped within the diagrams without abstraction. This adds more confusion than clarity for the reader.

Also, after reading the team's response, I still believe that the team should try to fix the typos, and let the reader know when a typo is intended. It is not clear when a word is meant for the correction engine, and when a word is simply a typo in the DG, as there are multiple such typos. For example, Suggesiton in the architecture diagram is probably not something that is sent to the correction engine.

Therefore, I believe that there is indeed a documentation bug in the diagram. I hope the team can take action to resolve this bug instead of ignoring it. Fixing this bug will enable developers to understand the documentation better.

---