nus-pe-bot
commented
3 years ago Team's Response
The usage guide is not be meant to be read sequentially. The preambles are hyperlinked from the relevant commands.
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: This is a bit odd for a justification. If the preambles are hyperlinked from the relevant commands, that seems to indicate the intention to have readers understand the commands before the preambles. But then why would the preambles be listed first, if they're supplementary to the understanding of the commands, especially if there's so much preamble? Which is why I think this qualifies as a documentation bug, or at least poor guide structure.
Furthermore, though the preambles are linked from the commands, the commands themselves are not (or rarely) linked from the preamble, so it's hard to follow along with the preamble.
:question: Issue severity
Team chose [severity.VeryLow]
Originally [severity.High]
- [x] I disagree
Reason for disagreement: In retrospect, severity.High may have been a bit much. However, I do think the preamble is very dense and impairs understanding, and the choice to present it at the front should not be handwaved by claiming that the UG is not meant to be read sequentially (especially since, as mentioned above, the preamble itself contains only a few links that would aid in reading the UG non-sequentially).
I think this fits severity.Medium, since it does inconvenience readers but the product can, of course, still be used:
severity.Medium: A flaw that causes occasional inconvenience to some [readers] but they can continue to use the product.
The UG starts with 8 pages about interpreting errors, incorrect formats, parameters, and so on, and uses various commands as examples even before any of the commands are introduced. This makes it difficult to follow this preamble as the commands are not even known to the user yet.