vaidyanaath / pe

0 stars 0 forks source link

Wordy examples involving hyperlinks #13

Open vaidyanaath opened 1 year ago

vaidyanaath commented 1 year ago

image.png

The description for all commands involving hyperlinks is extremely wordy, especially how each link is repeated at least twice. This is confusing to read since the reader wonders if there are 4 or more url links involved.

This was observed in add_docs and edit_docs

nus-pe-script commented 1 year ago

Team's Response

While the tester may argue that the description for the examples given are wordy, this is subjective.

The reasoning behind including the hyperlinks again is for clarification instead of confusion, which is important for a user guide which is designed to clear the doubts the reader.

It is very unlikely for the reader to wonder if there are 4 links involved. This is because each link is only repeated once, different from what the tester repeated which is at least twice, so there would be at most 4 links present in a sentence. The repeated links in the description serve to complement the explanation for the command formats below:

add_docs INDEX rs/RESUME_LINK cl/COVER_LETTER_LINK and edit_docs INDEX [rs/RESUME_LINK] [cl/COVER_LETTER_LINK]

If the description is not provided, users may instead be confused which part of the command is the prefix (rs/ and cl/) and which part is the actual link provided, especially when there are multiple slashes involved.

The situation of wordiness is also well handled by giving the command and the links a different font and text colour from the remaining part of the description which act as explanations.

It is also nearly impossible for the reader to wonder if there are more than 4 links involved as there are at most 4 links in an example for all commands involving hyperlinks. Each example belongs to its own bullet point instead of being cramped into a single sentence.

The extra clarification obtained by including the links again in the description provides extra convenience to the user instead of inconvenience.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: [replace this with your explanation]