search

liping-eng / pe

0 stars 0 forks source link

Structure looks not well-formatted. #16

Open liping-eng opened 3 years ago

liping-eng commented 3 years ago

There is no clear sub-headings for each feature and it was difficult to see all the features provided by LocationBuddy.

Either a summary of a table of features, a list function to show all the features or a table of contents will be useful.

Explanations were very brief as well.

Overall, the user guide looks very rushed and messy to comprehend.

image.png

nus-pe-bot commented 3 years ago

Team's Response

  1. Clear subheadings were provided in markdown (see https://raw.githubusercontent.com/AY2021S2-CS2113-T10-2/tp/master/docs/UserGuide.md).
  2. There are only five main features. Do you really need a list of all features in a two-page document?
  3. Regarding explanations, the amount of explanations per feature is roughly equivalent to the one given in the AddressBook example (see https://github.com/nus-cs2113-AY2021S2/addressbook-level3/blob/master/docs/UserGuide.md).

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: There is no clear sectioning such as numbering of each section and its sub-sections. As the font size is similar and there is no colour coding, it makes it difficult to read at a glance. There is only one type of colour coding and is used across a few places in the explanation of each feature, e.g. format, example of usage uses it.

The UG also looked rushed and messy. Here is an example of sentence structure that seemed cut-off because of the bullet points. There is also a general lack of full-stops after sentence that ends with keywords.

image.png

What could have been clearer would be to use other types of markdown, especially for example of usage.

A code snippet like the following could have been used to draw distinction between different parts of your elaboration on each feature.

*insert expected output*

Another room for improvement could be to make it clear which part of the UG is a section and sub-section. Below is an example of what I mean.

  1. Feature 1.1 listAllLocations 1.2 search ... and so on.

:question: Issue severity

Team chose [severity.Low] Originally [severity.High]

Reason for disagreement: There is an attempt in sectioning. severity.High as UG does not seem like it was ready for release and there is a good room for improvement as mentioned in reason for disagreement.