Learnability: Structured Learning - Beyond Basics --> Create content for 'Collaborating in GitLab'

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Summary: 'Collaborating in GitLab'

The content topic addresses the need to provide very basic information for users new to Git and GitLab by providing them with essentials to help them understand how to collaborate within GitLab. This can help them in applying their knowledge of Git and GitLab to their job.

Supporting research
  • Recent research revealed that users new to GitLab may not fully understand how collaboration happens within GitLab. As a result, they have to search online to understand this topic, which may or may not be helpful, depending on what they find. We can help here by: 1) making it easy to locate this content, 2) provide a simple narrative to answer the questions outlined below, and 3) cater the content to align with our messaging of GitLab, if appropriate. Providing this information can help new and existing users better understand the collaboration model with GitLab and to use it.

Questions the content should answer

  • "How do you collaborate within GitLab?" - this can go into using comments, @-mentions, etc. to keep collaboration on a given topic moving
  • "How does collaboration work within GitLab?" - this can go into what happens as soon as someone is @-mentioned (notification), if someone is added as an Assignee or a Reviewer or a Participant (ex: are they all notified automatically?). What happens if you just leave a comment in an issue or MR? etc.
  • "Who sees my comment within GitLab?" - this is important to know; especially if there are many participants on a given issue and the comment wasn't intended to be seen by some of them. @-mentioning doesn't mean a private message.
  • "What do people see when I @-mention them?" - the answer here should cover email, notifications, etc., along with the knowledge of 'it depends on the settings the @-mentioned person has'. Ideally, this should give them the information to confidently know what happens when they @-mention someone.
  • "Who gets notified when I leave a comment within an issue?" - this answer should consider the fear of a user spamming people who are already participants of the issue. Unknowingly spamming a group of people is a real fear and potential blocker to collaboration. We can make it clear to users what happens here to help address that fear.

Existing content

This would be content that currently exists on the given content topic. In cases where existing content exists, we can just leverage all or some of the existing content.

Examples of other content that answers the questions

  • None really surfaced up in a search

Content gaps

These are areas in the existing content that aren't answering the main questions the content topic aims to address.

  • The content examples above didn't go into explicit detail around how some of the collaboration interactions work. Specifically, what exactly do people see when you do something. Having this explained reduces stress and avoidance since there's no guessing. Perhaps a real-life example, from start to finish, of an issue or MR may help illustrate the functionality.

What needs to be done?

This section describes the work that needs to be done for this content topic. This could be reusing or adjusting existing content, or creating new content to address any content gaps

  • Create content to address the above gaps.

How will this content be accessed?

How users access the content is something that needs to be considered. This section documents how we designed the content to be accessed by our users. For example: the tutorials page, YouTube searching, etc

  • XYZ

Where will this content reside?

Related to how content will be accessed, it's also important to understand where this content will reside. For example: YouTube, the docs site, etc.

  • XYZ

Link(s) to the final content

Please link the final content (in the form of MRs) to this issue.

Edited by 🤖 GitLab Bot 🤖