soc-se-bot
commented
1 year ago Team's Response
We hear you but this is somewhat subjective as well. On one hand, it is convenient to have constraints for prefixes together with the commands. Yet, on another, it seems reasonable to have a separate table to comprehensively go through the description, usage and constraints of each prefix since prefixes are likely re-used in several commands.
Further, it is also nice to 'de-couple' information regarding prefixes from the commands so as to not:
- overload reader with too much information, the intent of the individual command section is to understand the command and not be bogged down by too much info
- repeat ourselves in many places
Perhaps we can consider a VeryLow severity if you can make a stronger point?
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: ## Why I insist on the current solution
I understand the need to avoid overloading the reader with the information but I still it would better to have the constraints for each field to be described within the commands rather than in the prefix table. This is because users will likely refer to the command sections for help on certain commands they need to do. As such, as a user, knowing what the constraints as well when looking upon on a particular will be more convenient compared to constantly navigating to the prefix table.
I can suggest that you can have a brief description of what each prefix is. (minus the details such as constraints) while having the constraints mentioned in the commands. I understand doing this causes repetitions for fields that are used in more than one but I feel that compared to reverting to the prefix table again and again, this method is more convenient for the reader. Moreover, I feel that some of the constraints you have mentioned can be omitted in User Guide and can be reflected clearly via other means such as error messages and in-app help.
Alternate solution
However, that be said, if you wish to continue with having the Prefix Section Table to be referred, I can suggest omitting some of the details, description for each field more concise for the reader as currently, it seems like information for some of the fields (e.g. Email) can be a lot to take in for the readers.
In this case, it would be better to show the description as such:
[name]@[email].[domain name]
[name] = [give small desc]
[email] = [give small desc]
[domain name] = [give small desc]
Note that the above structure is just an example
Moreover, in case of email, constraints such as constraints of domain name can be reflected as an error message in the application
## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Low`] - [x] I disagree **Reason for disagreement:** This is still a case for concern since the amount of information fed in prefix section table is a lot for the reader, which would go against the developer's intention to not overload the readers with information.
The Prefix Section Table is too detailed.
I understand that this is to brief me on what each prefix represent but it would be more appropriate to place it together with the commands. This way I do not have to scroll to the prefix table again and again to understand what each prefix requires.