soc-se-bot
commented
2 weeks ago Team's Response
Thanks for pointing this out. In our User Guide, when explaining how we convey the meaning of command formats under the General Notes about Command Format section, we specifically mentioned that
Items in square brackets are optional.
Note that entering list will execute the list command successfully, thus it is necessary for us to indicate that the parameters all, contacts, allcontacts are optional.
While we will recognise that readers who did not read this part may find such command format slightly misleading, we feel that a reader would have read a document from the top to the bottom (i.e., the “General Notes about Command Format” would have read first). Even then, our other commands format, such as add, edit and find command formats used square brackets to indicate which command parameters or fields are optional. The use of square brackets then did not seem to cause any confusion, thus we find it reasonable to believe that the use of square brackets in list command format to indicate that it’s optional will not mislead readers as well.
Although we certainly understand where you are coming from (the short time of PE would understandably make readers unable to carefully internalise the documentation), as writers of documentation, it is almost impossible for us to write in a way that appeases every single reader. For example, would we have to write a small tip for the use of square brackets in every command section where the square brackets are used, or would that be too repetitive? This is a subjective viewpoint and we stand by the latter, thus we strongly believe that saying once in the “General Notes about Command Format” suffice.
In a way, we feel that this is an unfortunate case of lack of close reading.
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [ ] I disagree
Reason for disagreement: [replace this with your explanation]
In the instruction for the 'list' command, based on what was written, my first instinct was to key in 'list [contacts]'. However, the actual command was 'list contacts', without the brackets. This was a slightly misleading instruction.