Feedback issues should be threads

[kyyberi]

Current look and feel

Need

As API owner I have no opportunity to respond to feedback. In addition I would love to see that feedback list behave like a threaded discussion so that there can be back-traced discussions, not just notes. This came to my mind when I was thinking to ask my developer network to give feedback about the API design by putting feedback with our tools in the feedback tab. I really would like to respond and discuss the item there, not just remove it. Responding would be engaging.

Goal

added by @bajiat 2017-10-06

• [ ] Any registered user
  • [ ] can reply to a public feedback item
  • [ ] can reply to a reply item
• [ ] The username of the person giving feedback or replying to feedback is displayed along with the feedback
• [ ] If a user is replying to an existing feedback item or another reply
  • [ ] There is a UI text indicating who the user is replying to
  • [ ] The replies to an original feedback item are displayed indented
• [ ] API owner and admin can
  • [ ] make all feedback private
  • [ ] make an individual feedback private
  • [ ] delete a feedback item
• [ ] Any registered user can upvote or downvote an individual feedback item

Mockups

Archive includes desktop and mobile views. feedback.zip

Here you can see basic prototype: https://invis.io/SYDU0V94C

[kyyberi]

To make it short, like Github issues.

[Nazarah]

1+ with the feedback thread. To me, it can also be GitHub issues. The same can be considered for backlogs. API consumer of a particular API would be eager to follow what new features, changes, etc. would be added to the API and might express what they wish to see in future development. Maintaining such thread to GitHub is a good place to start. I wish to know more cases on how this can be maintained in case of private APIs.

[kyyberi]

This is side note, but I'll add it here anyway so I don't forget it. Commenting in place would be awesome feature: paint text in documentation and leave a note (much like in Google Docs). I don't know how to handle it UX wise or technically. And would it become a mess (probably to some level.) Anyway, jumping to separate place to add feedback is not best possible solution anyway.

[kyyberi]

Not all use Github, so we can not rely on that. Adding opportunity to sort of sync the "issue" discussion on APInf and github issue list would add complexity for the admins but also in implementation (perhaps). Since all do not use Github there has to be alternative. Opinions from @brylie @philippeluickx would be appreciated.

[brylie]

I can see a desire to comment on Feedback, as well as other 'entities' in our platform. E.g. users might want to comment on any of the following:

• API/Organizaiton related media
• API Backlog items
• APIs
• Organizations
• ...?

For flexibility, we could have a structure such as:

• comment
  • entityId: ID of related entity'
  • entityType: name of related collection (e.g. Feedback, BacklogItem, etc)
  • text: text body of comment

Then, we could feasibly have a relatedComments component that

1. takes two arguments
   • entityType
   • entityId
2. renders related comments, possibly with pagination, etc

In that case, comments could also have comments (recursion/nesting).

[philippeluickx]

In all fairness, I've often said that we should have "the github for APIs". Not sure what Swagger Hub's role is here.

• If feedback is mainly about the API, then comments should live with the Swagger file and the Swagger file should be hosted on Swagger Hub
• If feedback can be about anything (also SDKs, examples, blog,...) then we just copy Github issues. That will include a lot more functionality (e.g. search)

[kyyberi]

Imho feedback is not only about Design, thus copy Github issues.

Swaggerhub is atm the only online usable tool to do API design (with swagger) and keep them in one place. Our current model is to support API creation from start to end. Anything less is swimming against the mainstream.

There can be different opinions about the swaggerhub's usability, but it fulfils for example my needs pretty well and I'm ready to forgive shortcomings in UX for now. Is it really worth the effort to replicate swaggerhub functionality to APInf even with better UX. I know there is API design editor stub in our repos, but IMHO that's waste of time and resources. IF we can find simple way to avoid for example another login to swagger to give feedback, then the comments could and should live there. Requiring another login (and account) to give feedback about API design is a barrier and will drop feedback significantly.

[kyyberi]

Clicking title row (or at least the feedback title text) should open/close the feedback.

[55]

@saransh-dev please check mockups section in description and let me know ASAP if you have any questions.

[saransh-dev]

@55, Do i need to change the UI of feedback? Currently we have following feedback UI.

Please advise.

[55]

@saransh-dev correct, take a look at mockups in archive I attached.

[saransh-dev]

@55 Yeah, I have checked it. Ok then i am going to change UI of feedback as you provided.

[55]

@saransh-dev if you have any questions, please don't hesitate to contact me here or in chat.

[saransh-dev]

Hi @55 , I have some confusions :-

1.Why we need to provide two reply buttons?

2. Do i need to common layout for comments (because user might also comment on API/Organizaiton related media, API Backlog items, APIs, Organizations and etc) or i need to different comment layout for feedback?

Please advise.

[55]

1. Second reply is to the comment (reply to the reply). Also there is only one level of nesting, means replies to replies should be on the same level. Reply to the reply has name of the user he replies to.

2. Use the provided layout, other places will inherit current layout in the future if needed.

[marla-singer]

@55 @Nazarah I have a lot of questions about these part

1. What about edit/delete Reply?

make all feedback private

2. What about "make all feedbacks public"? The early implementation has logic for that

3. The reply of reply must be as nested element. Because it isn't obviously that it is a reply of reply and what is the parent of current reply.

Look at the screen below. The numbers mean the order I added the items.

4. As for me the lock icon needs a help text like "Make all feedbacks private" because it isn't obviously

5. Also I don't like that we have an additional step for control visibility as Modal form. Does it really need?

6. API owner and admin can make all feedback private make an individual feedback private delete a feedback item

What about feedback author permissions? The early implementation has logic for that

[55]

@marla-singer @saransh-dev sorry for the lack of the description for the provided mockups. I will add a more prominent description during today. Also, can we move the rest of the discussion to the opened PR? (including your comment)