Skip to content

2019Q2 UX Scorecard for Creating a Merge Request

Job To Be Done

Creating a Merge Request: When I think my work is done or I need advice, I want to know what changes or improvements are needed, so that my work can be merged knowing it will behave as expected.

Experience baseline

Mini usability study (Think Aloud Protocol): https://drive.google.com/open?id=1TTrs9kmivwxLu-oKq_Weqe4-_YcnwdOZ

Experience walkthrough: https://www.youtube.com/watch?v=WOdqw_z2dwE

Benchmark score

Due to the fact that a merge request combines multiple smaller (and sometimes contained) tasks, I chose two different scores and added the separate tasks to each one of those.

Benchmark score C (Average) D (Presentable)
Tasks Template, Labels, Milestones, Assignees Approval rules & Changing branches
Description Workflow needs improvement, but user can still finish completing the task. It usually takes longer to complete the task than it should. User may abandon the process or try again later. Workflow has clear issues and should have not gone into production without more thought and testing. User may or may not be able to complete the task. High risk of abandonment.
Frustration Medium High
Task completion Successful but with unnecessary steps Unlikely, but there may be a chance that there is completion
Steps to complete task Average complexity Excessive

Job stages defined according to the Job Map.

1. Define: Determine goals and plan resources

Step Screenshot Emotions (grading scale)
1. I push my work to the repository from the CLI
2. I visit the project and a notice encourages me to create an MR. image 🙂 I feel delighted because it's contextual and timely.

2. Locate and prepare: Gather items and info needed, and set up the environment

Step Screenshot Emotions (grading scale)
3. I click the “Create merge request” button and I'm directed to the New merge request form. image 😐 I was expecting this.
4. I see that the “Title” field is pre-filled with my last commit message. image 🙂 I find it helpful because this already gives me something to work from and provides context.
5. I choose a template. image 😐 I was expecting this.
6. I scan the template text in the description field. image 😮 Wow, this is overwhelming. I don't know where to start
7. I switch to Preview to get a better overview. image 🙁 Now I can either see what it would look like rendered or add new content to it. I don't like this switching.
8. I try to find what applies to me. image 😧 I don't know the answer to some of this. Maybe this is for somebody else?
9. I start to add my information. image 🤔 What if I can't fill out some of the fields? Should I leave it open, add a comment, or delete it?
10. I check off my first items. image 😮 I can't do so in the Preview, but I have never done this in Markdown. Do I really need to read the documentation now? Afterwards, I also have to switch to Preview again to see if I did it correctly.
11. I notice /label ~new-feature at the bottom of the description field. image 🤔 What does this mean? Can I add labels like this? And what other stuff can I add like this?
12. I try to add a new label and after typing /, a new menu appears. image 🤔 I can't scroll down further, does that mean these are all options that are available to me?
13. I notice the “Labels” fields further below. image 🤨 Didn't I add a label in the description? Guess that didn't work then...
14. I add three new labels in the dropdown. image 🙂 That was quick.
15. I see "1. Contribution + 2 more" as text for the dropdown, and already forgot what the third label is. I open the dropdown to see which one I selected. image 🤐 I can't see my selected labels anywhere on the page anymore. Do I really have to scroll down through all labels in the dropdown? There has to be a better way.
16. I notice the “Assignee” field. image 😧 I'm confused, not sure what it is for. With the “Assign to me” link next to it, maybe I should assign myself to the MR. So I'm guessing this is for the author or creator of the MR?
17. Below, I see a section dedicated to “Approvers” and a line saying “All members with Developer role or higher and code owners (if any)”. image 😵 I'm even more confused. What is the difference between Assignees and Approvers? Are approvers the people that will review my work? Are all members supposed to approve my work? I didn't add this, so this must be a default, but per project or for all of GitLab?
18. I see another hint saying Tip: add a CODEOWNERS to automatically add approvers based on file paths and file types. image 🤯 Where am I supposed to add this? And am I actually the person who should do so? The documentation gives the impression that somebody who administrates the project should do it.
19. I notice that the rule has 0 required approvals. image 😲 This section looks complex even though it's seemingly not doing anything, because there are no required approvals.
20. I click on “Add approvers”. image 😟 Adding approvers is what I want now. But do I have to delete the other entry with 0 required approvals afterwards? And how can I do so, I haven't seen a Delete button so far.
21. A modal appears. image 😐 This is what I expected.
22. I see the Name field. image 🤔 What do I have to fill in here? I can try the name of the person I want to add as approver, but nothing shows up, so this is probably wrong. The hint says QA or Security, so maybe I have to add groups here? I will just leave it empty for now.
23. I see No. approvals required. image 🤔 This is interesting, it goes higher than the number of approvers. Does this mean that person has to approve 5 times?
24. I search for a member. image 🤯 I know that this is the persons username, why doesn't he show up? Oh, it looks like I have to omit the @. But I do it like this everywhere else in the UI, this does not make sense!
25. I select a member. image 🙂 Great, let's move on!
26. I submit the form. The “Members” field shows two errors: “Please select and add a member” and ”Please select a name”. image 😡 I'm frustrated, I selected a member, why would I also have to click on Add? And what name am I supposed to use?
27. I click on “Add” and the member is added to the list of approvers. image 🙁 I was expecting this but it feels unnecessary.
28. I choose a name. image 😩 I still have no idea what to use for this. Will others see the name I choose? I guess I will just go with "QA" for now, as the hint underneath suggests.
29. I click on “Update approvers” and the modal disappears, showing the updated rule with the new name and its users. image 😍 It's nice that I can see exactly who is an approver.
30. I look at the people that I set as approvers. image 🤔 When I submit this form, will the approvers receive a notification? I'm afraid to spam all of these people.
31. I see "Source branch" and "Target branch". image 🤔 I'm working in a fork, is Master the master of my fork or the forked project? I'm not sure where I could see this, so maybe "Change branches" will bring up more details.
32. I click "Change branches". image 😨 Why is this a dropdown if I can't change it at all, why should this happen in a new screen? I'm very afraid I'm losing my progress, why can't I change this directly in the dropdowns?
33. I see the project and branches. image 😰 The button text does not make sense, I only want to change the branch, not compare it. Will I go to a new screen? And did I just lose all my progress? I guess I will have to try out, but I'm very concerned.
34. I get redirected to the previous page, all my progress is gone image 🤬 Are you serious? This sucks!
35. Guess I will have to fill in all the details again... 😡 I'm very mad, there is not much worse than filling in data twice, it's annoying and boring!
36. I see "Please review the Contribution guidelines for this project". image 🤫 But I already had all this work with adding my description... Guess I will just submit and see whether I did anything wrong.

3. Confirm: Verify readiness to execute

Step Screenshot Emotions (grading scale)
37. I review the form's information. 😩 I think I have everything set but I'm unsure if I have to specifically assign or mention someone to review my MR? I want someone to look at my work.
38. I notice the “Commits” and “Changes” tab below the form image 😐 Oh this is a surprise. This information is helpful but I wasn't expecting to see this after the form.

4. Execute: Carry out the job

Step Screenshot Emotions (grading scale)
39. I click on “Submit merge request” and I'm directed to the MR page. I see that all of the information I filled is there. image 😐 I was expecting this.
40. I see the approvers section and notice it says “…eligible approvers”. image 😐 Aha! This clarifies that these people are not all supposed to review and approve my work. They are eligible to do so.
41. I'm not sure if the approvers were notified, so I attempt to leave a comment mentioning one of them to see if they can review it. I start typing their name and a dropdown appears with their username. image 😍 This a relief because I didn't know their username.
42. I submit my comment and it's displayed in the “Discussion” tab. image 😐 I was expecting this.
43. This is taking too long, I will just add myself as approver, so I can quickly merge this. image 🤔 I don't know where to do so. I don't have an edit or add approvers button anywhere here, so I guess this is not possible? Ahh, maybe I have to edit the entire merge request, let's see!
44. I add myself as approver, so that I can quickly merge this. image 😐 Nothing new here.
45. I submit the changes and go back to the overview, so that I can approve and merge myself. image 😐 Nothing new here.
46. I notice that I did not get added to the list of eligible reviewers, so I still can't merge. image 🤥 Why would you show me that I did get added, but then not do so without showing any error message? Guess I will have to go back in and set the number of required approvals down to 0 now, but now I will just wait for somebody else to see it. And also, why do you show the name of the approval rule for "Requires approval from" if there is only one person, you could just give me their name directly, so I don't have to expand.

5. Monitor and modify: Assess execution and make alterations to improve it

Step Screenshot Emotions (grading scale)
47. I wait for someone to see my MR and review it. 😓 I hope that someone will see my MR. If the person I mentioned doesn't review this soon, I'll have to mention someone else.

6. Conclude: Finish or prepare to repeat

Step Screenshot Emotions (grading scale)
48. I receive email notifications of someone reviewing my MR and I can click to see their comments on GitLab. image 😐 I was expecting this.

Other flows (CLI, email, web editors)

  1. Define: Determine goals and plan resources
    1. I have pushed my work to the repository or created .patch files.
      1. After git push:
        1. In the CLI: 😍 I'm offered a URL to create the merge request from the GitLab UI, saving me time.
      2. Email: How do I create an MR via email by referencing the source branch or sending .patch files?
      3. git push option: 😡 There's no way for me to know about this feature unless I look at the documentation.
        1. ⚡️ Suggest git push options after git push.
    2. GitLab editors:
      1. Ace editor: 😍 Before committing, I'm prompted to start a new merge request if I type a new branch name.
      2. Web IDE:
        1. 😍 Before committing, I'm able to start a new merge request in one action.
  2. Locate and prepare: Gather items and info needed, and set up the environment
    1. Email:
      1. 😡 In the empty MR list, there's no indication of this feature.
      2. 😡 In the “New merge request” form, there's no indication of this feature.
      3. 😡 When looking at the MR list, the link to create a MR via email is at the bottom, out of view. The label is not very clear: email a merge request? Does it support .patch files?
      4. 😐 The modal shows my private email address and describes what I need to do. But it doesn't mention that I can send .patch files. Also, the security aspect of resetting the private email address has the same visual weight as the instructions.
      5. 😡 How can I change the default target branch, or set other MR attributes? I guess I'll have to navigate back to this list and edit the MR. The documentation explains this, but it's not linked from here and it only mentions the /target_branch quick action.
      6. 😍 Clicking on the email icon opens my email app and pre-fills the subject and body with some simple helpful instructions on how to submit it properly.
    2. git push option: 😐 The documentation explains this feature properly.
    3. UI: If I try to do it manually through the UI, there are some places where I may be able to do it.
      1. Branches page: 😐 There's a “Merge request” button, but I'm not sure if this is to create an MR or view an existing MR? I just pushed my work branch, so this should be to create an MR. On click, I'm directed to the new MR form.
      2. Commits page: 😍 The “Create merge request” button is clearly visible as the primary action in this page. On click, I'm directed to the new MR form.
      3. Files page:
        1. 😡 This branches/tags dropdown doesn't have a label, just the master branch name, which may confuse people that are not familiar with Git. When I switch to my work branch, I don't see any way to create a merge request.
        2. 😐 Via the “New…” dropdown in the header, if I click on “New merge request”, I'm directed to the new MR form. But it doesn't prefill the source branch with the branch I was in, similar to the other paths.
    4. GitLab editors:
      1. Ace editor: 😐 When I choose to start a new MR and submit the form, I'm directed to the new MR form.
      2. Web IDE:
        1. 😡 When I choose to start a new MR and submit the form, the browser then asks me if I want to stay or leave the page, and that the data may not be saved if I leave. What should I do? I'm confused.
        2. 😡 I click on “Leave” and it takes me away from the Web IDE, redirecting me to the new MR form. This feels unexpected and can be undesirable if I want to keep working.
  3. Execute: Carry out the job
    1. Email:
      1. 😡 How do I know if the MR was created? What's its URL?
      2. 😍 I receive an automatic email with the MR URL. This is a pleasant, unexpected surprise.

Tasks

  1. If your JTBD spans more than one stage group, that’s great! Review your JTBD with a designer from that stage group for accuracy.
  2. Document the current experience of the JTBD, as if you are the user. Capture the screens and jot down observations. Also, apply the Emotional Grading Scale below to document how a user likely feels at each step of the workflow.
  3. Use the Grading Rubric below to provide an overall measurement that becomes the Benchmark Score for the experience.
  4. Once you’re clear about the user’s path, create a clickthrough video that documents the existing experience. Begin the video with a contextual introduction including: your role, stage group, and a short summary of the baseline initiative. This is not a "how to" video, but instead should help build empathy for users by clearly showing areas of potential frustration and confusion. (You can point out where the experience is positive, too.) The Emotional Grading Scale you documented earlier will help identify areas to call out. At the end of the video, make sure to include narration of the Benchmark Score.
  5. Post your video to the GitLab Unfiltered YouTube channel, and link to it above.
  6. Create an issue to revisit the same JTBD the following quarter to see if we have made improvements. We will use the grades to monitor progress toward improving the overall quality of our user experience. Add that issue as related to this issue.

Emotional Grading Scale

Expand/collapse scale
  • 🙂😍 Positive: The user’s experience included a pleasant surprise—something they were not expecting to see. The user enjoyed the experience on the screen and could complete the task, effortlessly moving forward without having to stop and reassess their workflow. Emotion(s): Happy, Motivated, Possibly Surprised
  • 😐 Neutral: The user’s expectations were met. Each action provided the basic expected response from the UI, so that the user could complete the task and move forward. Emotion(s): Indifferent
  • 😮🙁😧🤔🤨🤐😵🤯😡😲😟😨😰🤬😡🤫😩🤥😓 Negative: The user did not receive the results they were expecting. There may be bugs, roadblocks, or confusion about what to click on that prevents the user from completing the task. Maybe they even needed to find an alternative method to achieve their goal. Emotion(s): Angry, Frustrated, Confused, Annoyed

Grading Rubric

Expand/collapse rubric

A (High Quality/Exceeds): Workflow is smooth and painless. Clear path to reach goal. Creates “Wow” moments due to the process being so easy. User would not hesitate to go through the process again.

  • Frustration: Minimal to none
  • Task Completion: Successful
  • Steps to Accomplish Task: Minimal

B (Meets Expectations) Workflow meets expectations but does not exceed user needs. User is able to reach the goal and complete the task. Less likely to abandon.

  • Frustration: Low
  • Task Completion: Successful
  • Steps to Complete Task: Minimal

C (Average) Workflow needs improvement, but user can still finish completing the task. It usually takes longer to complete the task than it should. User may abandon the process or try again later.

  • Frustration: Medium
  • Task Completion: Successful but with unnecessary steps
  • Steps to Complete Task: Average complexity

D (Presentable) Workflow has clear issues and should have not gone into production without more thought and testing. User may or may not be able to complete the task. High risk of abandonment.

  • Frustration: High
  • Task Completion: Unlikely, but there may be a chance that there is completion
  • Steps to Complete Task: Excessive

F (Poor) Workflow leaves user confused and with no direction of where to go next. Can sometimes cause the user to go around in circles or reach a dead end. Very high risk of abandonment, and user will most likely seek other methods to complete the task.

  • Frustration: Very High
  • Task Completion: Very Unlikely
  • Steps to Complete Task: Lacking
Edited by Valerie Karnes