search

rahhulleee / pe

0 stars 0 forks source link

11. Readability #11

Open rahhulleee opened 3 months ago

rahhulleee commented 3 months ago

Portions like these in the UG have too much words and code in a row and it's hard to read.

image.png

image.png

nus-pe-script commented 3 months ago

Team's Response

Thanks for highlighting this but we have explained the rationale behind using code blocks in our Formatting Conventions.

image.png

Also on the issue of 'lots of words', we believe documenting our functions as informative as possible outweighed the costs of readability. 👍

Items for the Tester to Verify

:question: Issue response

Team chose [response.NotInScope]

Reason for disagreement: image.png

According to this guideline, some parts are uneccessarily long and very nested, which indeed hinders readability, despite your bolding.

For example, regarding your add command inputs, you can just say ONLY birthday and remark are optional ; missing out on compulsory field = error.

For your email :

image.png

Shorten the above explanation to something like:

1) emails have to follow local-part@domain format (eg. hello@yahoo.sg) 2) only alphanumerics allowed in the local-part and domain area and special chars (+._-) 3) as per example, domain at least length of 2

Once again the readers have to get a simple user guide that gives them the important gists of using the application, and readability is very important. Some parts are unnecessarily long according to the guideline above.