Duplicate information and very messy to read and understand for list and convert command in DG

[woojiahao]

All of this information can be reported under the sequence diagram and condensed instead. The current state makes it hard to keep up and confusing for developers to understand.

Filing this under Medium severity as I believe that ambiguous and cluttered documentation can make it even harder to understand how a feature works and since this is repeated twice, I think it makes the DG hard to understand

[soc-se-bot]

Team's Response

Thanks for pointing this out, we do agree that it could be rather wordy, however, we would like to argue that this warrants a "Low" severity rather than a "Medium" because of the following:

1) We believe that the text is quite readable due to sufficient spacing and low word count. 2) The repetition actually explains the different commands in slightly different ways, and thus cannot be extracted out. 3) This only causes a minor inconvenience to the developer since the in depth text is required to understand the implementation.

Items for the Tester to Verify

:question: Issue severity

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

• [x] I disagree

Reason for disagreement: > We believe that the text is quite readable due to sufficient spacing and low word count.

The repetition actually explains the different commands in slightly different ways, and thus cannot be extracted out.

While this may be true, the duplication of the content can lead to confusion. For instance, the lines of "The execute() command in ListClientCommand and ListLeadCommand is executed." and "The execute() command in ListClientCommand or ListLeadCommand iterates over the persons list in the ModelManager object". The first line adds no additional information and the second provides some relevant information about how the execute behaves. Additionally, the "example usage scenario" simply re-iterates the points that were raised in the above section, albeit in a slightly different way.

It is this duplication that can be confusing to users and IF there are inconsistencies between both sections, there is a chance that the reader will be unable to properly apply the knowledge gathered from the DG to understand the commands in question.

This only causes a minor inconvenience to the developer since the in depth text is required to understand the implementation.

As mentioned above, the description of the behaviour can most certainly be more succinct and concise, capturing the essence of the command without repeating the instructions and confusing the user. Longer text != clearer text as the idea that is being conveyed can be muddled up and reduce the usability of the DG. This is especially apparent in the first example where there is 3 separate sections detailing how the same commands work: initial textual description, example usage, and sequence diagram. If this pattern of documentation is repeated for the rest of the DG, it can create points of inconsistency and make the overall DG very hard to follow and prone to confusion.

For instance, the team might change the behavior of the predicate and update the first instance documentation while missing the other two sections, causing the documentation to go out of sync.

---