GitLab UX Team, 30 Sep 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Summary of updates to the Product Design merge request review guidelines

Description

Pedro Moreira da Silva, Staff Product Designer at GitLab, shares the recent updates to the Product Design merge request review guidelines. These updates are part of our Key Result for FY22-Q3 “Improve the quality of design MR reviews” (https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/12127).

- Product Design MR reviews guide: https://about.gitlab.com/handbook/engineering/ux/product-designer/mr-reviews/
- Code Review guidelines: https://docs.gitlab.com/ee/development/code_review.html
- Preview, test, and contribute: https://about.gitlab.com/handbook/engineering/ux/how-we-work/#preview-test-and-contribute
- Design and UI changes checklist: https://docs.gitlab.com/ee/development/contributing/design.html#checklist
- Retro/feedback issue: https://gitlab.com/gitlab-org/gitlab-design/-/issues/1727

A

Hi product designers, I'm pedro and today I'll be sharing with you. Some of the recent updates that we've made to the merge request, design reviews guidelines and these changes were made as part of our key result for this quarter, to improve the quality of design, merge, request, reviews and as feedback that we got from the retrospective on the current state from you. uh You thank you so much again for giving your inputs in the survey in the internal survey. We collected that feedback and we made some changes to the guidelines.

A

So the first big change that we made was to dedicate a page just for the merge request, reviews guidelines and creates several sections uh with different topics to help you navigate uh these guidelines. So, first of all, one of the first things that we are addressing is a topic of requirement.

A

So here we explain which merge requests you are required to review and approve, and also uh how you can triage merge requests that your team creates to find out which merge requests are worth reviewing or not, and the other thing that we wanted to talk about was workload and response times, which was another topic that came out of the internal survey.

A

So here we clarify exactly how fast we expect you to respond to merge, request, reviews what to do to manage expectations and also how to balance, merge, request reviews with your other priorities, which can be a challenge because merge request. Reviews are often unpredictable. So we give you a couple of tips there to manage your workload.

A

And, finally, the core of the merge request guidelines is a reviewing section that has subsections to understand preview review hand off the merge request.

A

One thing I wanted to point out is that for all of these guidelines, as we say here, we try to follow the code review guidelines in general, which is a long document, but we recommend that you read all of it and the exceptions to those guidelines are noted below. So this page basically only contains exceptions to the general code review guidelines that I'm linking from here and that's lead you to this page that contains the guidelines that not only gitlab team members but also any contributor at gitlab will need to abide by and follow.

A

So it's a, I guess, I said a very long page, but please read all of it because most if not all of this also applies to you, a product designer doing design, merge, request, reviews.

A

Another thing that we wanted to clarify was how you can preview merge, requests which methods you can use today, how you can use them, how you can get started and what to do if you get stuck and need help. So in the how we work linking from here in this part c preview test and contribute, we added a new section to the how we work page, the how we work for the ux department and at the bottom of the page. You can also use the table of contents here on the side.

A

You can click preview test and contribute, and we describe the different methods you can use to preview tests, review, merge, requests and even contribute changes to the different projects, so the gitlab project, user, documentation, pajamas or even the company handbook.

A

We added a comparison table that you can expand here that helps you choose the most appropriate method, depending on how quickly you need to do a review or contribute changes and what features you need to use when doing those reviews or contributions.

A

We also added a get started section with specific links for git, pod, gdk and review apps. That help people understand how they can start using these methods if they want some of them even have videos, because I know many of you are visual people so sometimes watching a video is faster and clearer than reading through documentation. So some of them have some links to foundational videos, and we also link here at the top, a playlist on youtube, with walkthroughs of the gdk and git pod and how-to videos in general and finally, at the bottom.

A

We have this help section, which was recently added by tori and contributed with had other contributions by other designers, and we reformatted this section slightly to be a bit more descriptive and easier to follow with specific instructions.

A

So back to the merge request, reviews guidelines.

A

As I said, the core is the reviewing part, and here we link to our design and ui changes checklist, which is a new thing that we're adding and it basically is a support to help. You make sure that all aspects are covered by the merge requests, and this checklist is linked from many places. You can click here to get to it and we've added this to the user. uh Sorry, the contributor documentation, because it applies not only to gitlab team members but to any contributor who is designing or reviewing design and user interface changes.

A

So in the checklist- and you can use this checklist, as I said to not only when reviewing, but also when designing, to make sure you're covering everything we have. Sections for writing patterns, states, visual design, responsive accessibility and handoff and follow-ups, and in this case handoff is mostly applicable.

A

When you are, you have completed your design and you're handing it over to engineering for development and follow-ups is mostly applicable when the design is complete or the merge request is approved and merged, and you want to document specific things that need to be improved on or need to be done after the merge request is merged.

A

I said in the beginning, this is all part of the q result that we have this quarter and we're asking a number of designers from different stages to complete a merge request review with these guidelines, and we even created a retrospective slash feedback issue, where you can give your feedback on how these updated guidelines have helped you or not, or what we can improve, and this is it. Thank you so much for your time again. I hope that these guidelines definitely help you reviewing merge, requests and I'll see you around ciao.