Lack of diagrams in the developer guide.

[DannyDakota]

For the features that are present in the developer guide. Only either the class diagram or sequence diagram or both is shown. No inclusion of an activity diagram to show the steps the users will take. This disallows a potential developer from fully understand the implementation of the feature and how the user may interact with the application.

[nus-se-bot]

Team's Response

The main point seems to be that a potential developer might not understand how the user is supposed to interact with the software because no activity diagram is present in the developer guide. However a developer is expected to have access to the user guide, and it should be enough in describing how the user is expected to interact with HackNet.

Items for the Tester to Verify

❓ Issue response

Team chose [response.Rejected]

• I disagree

Reason for disagreement: The response by the team is pinned on a few assumptions. Firstly, the Developer Guide can omit details as the developer can just refer to the User Guide. Secondly, the developer can understand the technical execution by reading the User Guide alone and lastly, it is convenient for the developer to easily switch about different guides to understand the underlying implementation.

To address the first assumption that the Developer Guide can just omit details as the developer can just refer to the User Guide, this defeats the entire purpose of a technical document. The purpose of a technical document as taken from the CS2103T Website is :

The omission of diagrams such as activity diagrams that are specific to helping the developer understand program behaviour results in the DG being incomprehensive. If the DG were to omit details, then where exactly can a developer go to understand the underlying program behaviour? This brings me to the next assumption given by the team...

The second assumption is that the User Guide "should be enough in describing how the user is expected to interact with HackNet".
The purpose of an activity diagram is to model workflows. Taken from the CS2103T Website:

Activity diagrams allow the developer to understand the underlying workflow when a particular feature is being run. There are multiple actions/branches that can be taken, and different flows to achieve the intended result. The team, however, states that the developer is able to understand all these from the User Guide alone. Let us refer to a specific feature, for e.g the delete feature. By having the developer refer to the User Guide only as the activity diagram is omitted, the developer will only be able to gather that the index needs to be valid (referring to an index number shown in the list), and that if the command is valid the person is deleted. This completely leaves out technical details describing the underlying workflows that are the primary purpose of an activity diagram in the developer guide. The developer won't know what happens in the application when the command is invalid, what are the workflows taken to delete a user when the command is valid or what exceptions are being thrown to handle the different errors(ParseException or CommandException??).

Lastly, the last assumption is that the developer can just refer to the User Guide easily. When skimming through a technical document and reading about a specific feature, having your information displayed in a clear, comprehensive and comprehensible format allows the developer to fully internalise the underlying implementations enhances the readability of the developer. However, having to consistently refer to the User Guide while reading the Developer Guide, made worse by the fact that the User Guide does not encompass the technical information required, greatly hinders the reader.

This issue is exacerbated by the fact that there are no activity diagrams at all in the Developer Guide other than the existing AB3 activity diagram. Therefore, this piece of technical document is lacking.

Taken from CS2103T Website:

---

❓ Issue severity

Team chose [severity.Low]
Originally [severity.Medium]

• I disagree

Reason for disagreement: As stated in my reason for disagreement for issue response, This is a severity medium as the developer can continue to use the product, but the lack of such diagrams causes inconvenience to the users as the DG is not comprehensive by leaving out these details, and thus most developers will have to refer and trace through the actual code actually to understand what is going on.

---