search

craeyeons / pe

0 stars 0 forks source link

Vague explanation for sorting order. #15

Open craeyeons opened 1 year ago

craeyeons commented 1 year ago

image.png

I think the choice of words here can be better. "back to default (unsorted)" is vague, "chronological order" may be better.

nus-pe-script commented 1 year ago

Team's Response

Hi, thanks for the suggestion!

Although the default sorted order is chronological (currently), we don't think the user needs to know this information (though is obvious based on the UI). Reason being, we may wish to change our default ordering which would require an update to the UG again. Rather, documentation should be as robust as possible to future changes and so, we shouldn't be giving too many specific details. (Another issue is that chronological might not be a common term known by everyone)

Further, a "default ordering" is quite natural and is commonly used by other applications. It is not vague because the default order simply refers to the order in which the application decides to show the list of members (without any sorting - alphabetical or reverse). It is deterministic and consistent, which makes it unambiguous. Users should not have to know why the default order behaves the way it does as long as it is the same every time.

Hence, we don't think this is a bug (but we do appreciate your suggestion!)

Have a nice reading week ahead and best of luck for finals!

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: There is nothing natural nor canonical about "default ordering" implying "chronological order". Unsorted may very well mean that it is jumbled up randomly.

While I do agree that the User Guide should not include too many details, but we should not convey 0 detail in the user guide.

we don't think the user needs to know this information (though is obvious based on the UI)

If so, how do you expect the user to know how this works?

Reason being, we may wish to change our default ordering which would require an update to the UG again.

Doesn't this imply that default can be used to mean a lot of things and is indeed vague?

I genuinely do think this is a documentation fault. Even a mere "back to the original order before sorting" would be a better phrasing.