soc-se-bot
commented
1 year ago Team's Response
We get where you’re coming from, but we feel doing it this way is still the most sensible way to go about it. These points are all related to how we denote the format of a command and they are relevant to many of the commands in the UG. If we were to instead try to split up the points and add them next to every command that requires them, that would cause a lot of duplication of the same points. Doing it this way instead allows for one cohesive box to explain all the relevant info the reader needs to know before digesting the rest of the UG.
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: [ I do believe the team misunderstood the issue that I reported. I do feel this is a purely cosmetic issue because the information box is not purposefully used. Since the entire command format needs to be listed out, it might be better to put this as a section of its own -- introducing a new section that people can click to straight from the ToC as well, which could be useful for beginners especially. I have edited the HTML code to show a possible solution to this cosmetic issue.
In the following image, I have arranged all the points under a section of its own with the header ## Notes about the command format. This allows users to quickly reach the command format section from the Table of Contents. Next, I have replaced the information box with additional information that the user might need to know, this way the box is more purposefully used as the user would be able to spot a distinct Information header within the entire UG, which is shorter and easy to digest. Lastly, since all the points of the command format have been extracted, they have been placed outside of the information box, under the entire ## Notes about the command format header. This way, the user also has a cohesive section that explains all relevant information about each command, before continuing with the rest of the user guide.
]
Issue
To group the entirety of how the feature works into a singular information box might not be the most ideal. Since the entire paragraph is needed, especially for beginner users to go through before understanding, maybe group them up into points that people can read rather than placing everything into a singular information box.
This defeats the purpose of placing information boxes in your User Guide because it makes each occurrence of the Information box highlighting less important.