DOJO: Discussions Design Doc

[HS-90]

Related to issue #2252
This relates to C0D3 DOJO Design doc #1192 and includes a more detailed documentation of the implementation of the discussion component.

Intro

Current UI design for discussions in Figma(unfinalized): https://www.figma.com/file/f9xRyl1bJOjtBRd8zFORzg/c0d3?node-id=404%3A13721

Current Component Design in Codebase:
https://deploy-preview-2339--youthful-thompson-448332.netlify.app/?path=/story/components-discussionscard--discussions-card-main

Goals

Students can benefit immensely from communicating with mentors and fellow students while working on lessons, exercises, and challenges.

Problem

While students can currently discuss topics on Discord, conversations can drift towards different topics, older messages that have valuable information get buried and become hard to track down over time.

Solution

Having a discussion forum within C0D3 can serve as a valuable tool to discuss topics, concepts, projects, exercises, etc. It allows for better organization of the lesson/exercise being discussed. It can also serve as a lasting reference for future students who run into similar questions or issues.

Sample Discussion Flow

Implementation

A model in Prisma and typeDef in GraphQL called 'ExerciseComments' should be created with the following properties(assumes id, createdAt, and updatedAt are always present):

ExerciseComment{
   authorId: Int (foreign key to refer to user who posted)
   exerciseId: Int (foreign key to refer to exercise being discussed)
   userPic: String? (url to user profile picture)
   content: String (body of post)
   parentId: Int?
   exercise: Exercise
   author: User
   parent: ExerciseComment?
   replies: ExerciseComment[]
}

In addition, exerciseComments: ExerciseComment[] should be added as a property to the Exercise and Usermodel and typeDefs. This way Discussions are linked to a specific exercise and the user who created the comment in the backend.

For use with DOJO exercise

On the frontend for DOJO exercises, our DiscussionsCard component should accept the following props:

type DiscussionsCardProps = {
   isMain: boolean
   username: string
   userPic: string
   timeStamp: string
   content: string
   editAndDeletePermission: boolean
   deleteClick: Function
   saveClick: Function
   sendClick: Function
   replies?: DiscussionsCardProps[]
}

Each comment section will be tied to an exercise page, and upon page load, a query will be sent to the backend to check for any ExerciseComment with an exerciseId that matches the exerciseId of the relevant exercise page. These exercises will then be loaded into the page.

If isMain is true, the post is considered the original/main post and will be styled like the following:

If isMain is false, it is considered a response to a main topic, and will be styled like the below:

The userPic should refer to a link that displays the user's profile picture. As of right now, users cannot upload their own profile picture. The students who do have a profile picture, are ones who linked their Discord account, and the image url is taken from a third party Discord link. If the profile picture cannot be obtained from Discord, we will use https://www.gravatar.com/avatar/${ hash } as a default placeholder.

The userPic, username and timeStamp is displayed on the header and content will fill the body of the post.

editAndDeletePermission determines if the user has access to the delete and edit buttons. Users can only delete or edit their own posts.

deleteClick, saveClick, sendClick, are all functions that will alter backend data.

When the user hits 'reply', or the 'edit' button, the click functionality will be handled within the component, rather than use a prop, as these buttons will affect the layout and functionality of the component, but will not send any data to the backend.

Displaying longer threads and pagination

If students create a comment chain with a ton of back and forth discussion and the thread becomes very large, we can only display a certain number of posts at a time. This will be handled with pagination, and users will need to click comments to expand them, and read replies that are further down the chain.

DiscussionCard Component Integration with Prisma ExerciseComment Table

isMain can be determined based on whether the comment has a parentId. If it has one, then we know it is a reply and not a main card.

username can be obtained from the comment's author, as it points to a User table, which will have the author's username

timeStamp will be based on createdAt or updatedAt if the user ends up editing the comment.

GraphQL Queries

On the exercise discussion page, there should be an initial query to load all Discussions relevant to that exercise and display them on the page.

User Interactions

When a user clicks on 'Save' after editing a post, there should be a query that changes the content of the post.

When a user clicks on 'Send' after replying to a post, there should be a query that saves the response data in the array of the replies property.

When a user clicks on 'Delete', there should be a query that replaces the content of the post with 'message deleted by user'

Action Items:

• Create initial design for 'main' and 'sub' DiscussionCards(completed)
• Create ExerciseComment type in prisma and GraphQL
• Add exerciseComments property to Exercise and User type in prisma and GraphQL
• Incorporate relational database structure between ExerciseComment and Exercises
• Queries and Resolvers for responding, adding, editing, and deleting a post
• Add UI frontend functionality for edit and delete functions
• Design and create layout for how replies and responses to replies will be displayed
• Create page layout of Discussions
• Integrate frontend and backend with Exercises.
• Add UI frontend functionality for saving edits, and sending replies.

Notes

Version 1 of the discussion component won't have a 'like' button feature.

Version 2, after the discussion feature has gone into production, we may incorporate frontend and backend functionality for a 'like' button.

Distinction between Discussions and Submission Comments

We currently have an existing feature that allows students and reviewers to discuss the student submissions for each challenge. It is initiated by clicking on a single line, and writing a comment pertaining to that line. This feature currently allows replies, but does not create sub-threads that continue to expand, thus does not require pagination.

The structure is as follows:

This is appropriate for it's purpose, as the discussion revolves around a single line, and students are for the most part very receptive to advice, so there isn't as much back and forth. The Discussions feature is meant to allow discourse over a whole exercise, rather than a single line, thus allowing for longer conversations. Having the option to reply to sub-threads is more appropriate for the latter feature

[SlyBouhafs]

Looks good, I have a few questions:

• Let's say we have main thread and a user sends a reply, then another user sends another reply, not to the main thread but to the first reply, how will it get displayed?
• What if we have 100 threads? How will it get displayed?
• What if a thread has 100 replies?

Do we have a UI design for those cases?

[HS-90]

All very good points

Looks good, I have a few questions:

• Let's say we have main thread and a user sends a reply, then another user sends another reply, not to the main thread but to the first reply, how will it get displayed?

I think we can come up with something in a future PR, then the team can decide how it looks and any tweaks/adjustments that need to be made.

• What if we have 100 threads? How will it get displayed?
• What if a thread has 100 replies?

In #2252 @flacial mentioned in the case of many threads or replies, we can implement pagination so that not all of them are showing at once, unless the user decides to expand all the threads and replies themselves.

Do we have a UI design for those cases?

I dont think we have one, but can be done in a future PR.

[SlyBouhafs]

I think we can come up with something in a future PR, then the team can decide how it looks and any tweaks/adjustments that need to be made.

I'm not sure i understand you, this design doc is about the discussions, leaving it to another PR is part of the implementation, breaking those features into different PR's is a good idea but we need to agree on how its gonna be before we get to design/implement it. It's probably better to answer those issues/concerns (I agree with @flacial suggestion about having something similar to what reddit does) in the design doc so once we get to the design part, we have an idea on how to design and implement it.

[HS-90]

I think we can come up with something in a future PR, then the team can decide how it looks and any tweaks/adjustments that need to be made.

I'm not sure i understand you, this design doc is about the discussions, leaving it to another PR is part of the implementation, breaking those features into different PR's is a good idea but we need to agree on how its gonna be before we get to design/implement it. It's probably better to answer those issues/concerns (I agree with @flacial suggestion about having something similar to what reddit does) in the design doc so once we get to the design part, we have an idea on how to design and implement it.

Oh I see. I was thinking along the lines of if we had something either coded up or drawn up in Figma, which I dont think we do. As of right now, are you saying it would be helpful to at least have some kind of description or maybe draw out a rough sketch/layout of how these features will be implemented?

[flacial]

Oh I see. I was thinking along the lines of if we had something either coded up or drawn up in Figma, which I dont think we do. As of right now, are you saying it would be helpful to at least have some kind of description or maybe draw out a rough sketch/layout of how these features will be implemented?

I think @SlyBouhafs is asking about how will it look when the replies look like the following:

Main thread
  - Reply A
      - Reply B to A

We don't have to create a new design but edit the one we currently have:

Actually, we need a new design for the nested replies. It's hard to edit the one in figma.

[flacial]

Once the nested replies reach 4-level deep:

Main thread
  - Reply A
      - Reply B to A
          - Reply C to B
              - Reply D to C
                -  Reply E to D
                - Expand thread... -> Once clicked, set the Main thread as the reply. To go back to the original thread, hit Back btn

[flacial]

Pagination:

https://www.apollographql.com/docs/react/pagination/core-api
https://www.prisma.io/docs/concepts/components/prisma-client/pagination

[evo777]

It is cool how you used my picture.