nus-se-script
commented
2 years ago Team's Response
Hi, thanks for the bug report.
Reason for response.Rejected
The reader does not encounter what a typical command looks like until they reach the features section.
This is not true. Right on the next page, the quick tutorial section, there is already a command.
In addition, of the ~20 commands in ArtBuddy, only ~6 follow the command format command_word INDEX prefix/PARAMETER, so this might instead confuse readers .
Also as the descriptions are pretty self-explanatory (eg: an index is "simply a number"), supplying examples don't seem to be very necessary here. Also, we've linked readers to the Appendix- which includes examples of command parameters. We did not want to clutter the UG with too much repetitive and unnecessary information.
Lastly, we believe that the next section (Quick Tutorial)- where users can try out real commands with the different formats would serve as the best introduction to commands in ArtBuddy (nothing beats hands on practice!). This section is meant to be more of a brief introduction/ preface to ArtBuddy commands.
Hence, this should not hinder the reader.
Hope that clarifies things. Thank you!
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [ ] I disagree
Reason for disagreement: [replace this with your explanation]
Most of the explanation of the command format is written in prose, without any examples given. This may be confusing for first-time readers of the user guide. The reader does not encounter what a typical command looks like until they reach the features section. A suggestion would be to put a general example of what a typical command looks like in each section e.g.
command_word INDEX prefix/PARAMETER.