soc-se-bot
commented
4 months ago Team's Response
The warnings are placed before the examples in order to well, warn users of important information in order to ensure that users are aware of the exact behaviour of the feature before haphazardly copying the examples.
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: While I understand there are reasons for the placement, I still believe that it causes some hinderance to the user. As a first time user myself, I found it quite difficult to understand what was going on, and sometimes the best way to understand is via examples. However, to find the examples I had to go through a list of edge cases that spanned over multiple pages.
Placing the warnings after the examples is not a horrible idea and I do think that as long as it is highlighted well enough, users will be able to notice the warnings. At the same time, it would not hinder the natural progression of learning about the command -> viewing examples -> being warned about edge cases.
I think that the user guide is quite good, but there is still some room for improvement and it might be prudent to explore avenues to improve it (at least at some point down the line) than to outright reject it.
As a reader, the fitadd command is something that is complex and has a lot of info. Having access to the typical examples before the warnings would help me greatly. Instead the warnings take up one page and I have to see the edge cases before I can figure out the actual command structure / some more typical uses.