search

connlim / pe

0 stars 0 forks source link

Misleading documentation about JSON format #6

Open connlim opened 1 year ago

connlim commented 1 year ago

The user guide provides a list of fields that the JSON data storage file uses. However the fields are not shown correctly as they are stored in the JSON schema. For example, all reviews are stored under an array belonging to their store, and only reviews can have the content key. This is not reflected in the documentation. Instead the documentation makes it seem that content is on the same level as other fields like address, which is not true.

Suggest to give a proper JSON schema instead of this list of fields in the user guide.

Screenshot

image.png

nus-se-bot commented 1 year ago

Team's Response

The example was provided in the developer guide but not in the user guide as this is a feature for advanced users.

image.png

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: If you are going to provide these details in the user guide, which advanced users will read, you should provide sufficient details in the UG alone for advanced users. They should not have to jump back and forth between 2 documents. Putting only half the necessary information in the UG and leaving the rest of the essential information in the DG is not good practice for users.