UX - SSOT
Merge request reports
Activity
@sarrahvesselov : Can you review or suggest updates?
cc @gl-product
Oftentimes, designers are providing great designs and updates. But they often get stuck in comments, and it is very hard to follow a discussion. In particular, I'd suggest that designers should just make updates to the designs in the description directly, because I found myself agreeing with a design 95% of the time and asking a designer to please update the description with latest, and often that doesn't happen in time because of busyness and things get lost. I'd rather designers just make a decision, update the SSOT description, and leave a comment indicating so. Especially for really small obvious tweaks, which are 95% of the time in the post-initial-design-catch-edge-cases phase, as well as during development. If there are any changes to the specs during development because of something an engineer raised, I'd rather designers make updates to the description. Currently it's pretty much me updating it, which wastes time since I'm often just the middle-person. The deep detailed discussions and decisions were had by the engineers and designers and so they have the best context.
Another thing that I find some designers do is that they provide great mockups in the issue description, but they leave my original specs/requirements in the issue description unchanged. Often times the mockups actually conflict with what I've wrote. I'd prefer if the designer just deletes (or at least uses strikethrough) the things I've written if they are no longer correct. I would like the designer to totally own the wireframe/visual compositions as well as all the text. This includes edge cases, describing UX flows that can't be easily described through the visuals, etc. etc.
This is an example of what I like in terms of process: https://gitlab.com/gitlab-org/gitlab-ce/issues/30126. But I think we take it even one step more and just remove the section that is "Original Proposal". That's just going to create more noise. Or we can easily use the
<details>tag if that helps. I'd hope that the designer can carefully read through all the edge cases I've considered, and keep whatever makes sense, throw out what is incorrect, and add anything else. Right now, it's essentially two sections, the PM section, and the UX section. Oftentimes I find myself not doing a good enough job of updating everything afterward. And as a result, engineering often doesn't get a very clear picture / SSOT.This is an example of what went poorly: https://gitlab.com/gitlab-org/gitlab-ee/issues/2001. I had some initial concepts, UX made some really good designs. We had a kickoff meeting (product+design+engineering) and we made a decision to split out some of the new visual design to a separate future issue, and use a very plain old design in this issue. But that's not reflected in the description at all right now.
Let me know what you think. Thanks!
I completely agree with this, yet I hesitate. I agree that long issues with designs in comments are difficult to follow, becoming confusing and convoluted. Just wrapping your head around what the issue is about can be challenging.
I hesitate because there is so much value in seeing these iterations (a reflection of the conversations) of the design. Replacing the initial design in the description is, in itself, disorienting. I can't tell you how many times I am reading through an issue trying to understand what the initial problem was based on the image in the description only to realize that it is actually the latest design, not the starting point. Context is lost and it can become difficult to grok whether the new ux is actually an improvement.
All of this is to say that the real problem is that issues in themselves are not capable of handling a true design discovery session. We have opened an issue to address this https://gitlab.com/gitlab-org/gitlab-ce/issues/33161 and I want to devote UX time to it in the next 2-3 months. This is not just a problem for us, it is a larger problem in the community and for design teams everywhere. Solving this could be huge.
I don't have an issue with the update but I don't think it will do much to solve the actual problem.
I agree with @sarrahvesselov it frustrates me no end when the description is updated and we lose history.
I'm going to merge this. Thanks for the review.
I agree with the larger design discovery aspect.
For this, I'm referring more to smaller, specific features that may be one of multiple iterations in a larger design. I would like to equip designers to be more empowered to make decisions and document them clearly. I will continue to work with designers and engineers and see how we can all improve.
mentioned in commit 7d29402a
https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/6345#note_31822003
@mydigitalself this is why i am pro getting description history in system messages... or a way to scrobble through description history ;)
-
I agree that long issues with designs in comments are difficult to follow, becoming confusing and convoluted. Just wrapping your head around what the issue is about can be challenging.
@victorwu @sarrahvesselov what about a way to collapse a lot of the comments (for everyone) from a certain point in the discussion.. so the discussion is once again very short and non convoluted?
Edited by Dimitrie Hoekstra 
This is an example of what went poorly: https://gitlab.com/gitlab-org/gitlab-ee/issues/2001. I had some initial concepts, UX made some really good designs. We had a kickoff meeting (product+design+engineering) and we made a decision to split out some of the new visual design to a separate future issue, and use a very plain old design in this issue. But that's not reflected in the description at all right now.
@victorwu Can you clarify here? I updated the description of this issue with the SSOT and the description contains the UX that was agreed upon:
https://gitlab.com/gitlab-org/gitlab-ee/issues/2001#note_27769807
https://gitlab.com/gitlab-org/gitlab-ee/issues/2001#note_27829723
Update: Eric is also asking for clarification on the retrospective agenda regarding this point.
Edited by Taurie Davis@tauriedavis : We had a meeting on April 19th about related issues. You weren't there. But @dimitrieh was there representing UX. Dimitrie had a bad connection for the call and I think he was traveling. So it was definitely not his fault that some of the communication wasn't very good. We decided during the call that we would use the existing visual design of Related Merge Requests to do Related Issues during the call. That is, we would not implement the new box design, but we would just use the existing visual design that still is present for Related Merge Requests now, but extend that to Related Issues. But nobody did a good job of documenting that in the issue after the call at all. It was primarily my fault (since Dimitrie had that poor connection and I think had dropped by this time). I did update the issue description (which is now changed, so you can't see the history), to indicate that we would use the existing Related Merge Requests design, and delay to use the new visual design in https://gitlab.com/gitlab-org/gitlab-ce/issues/31123. However, I left the unchanged mockup in the description. So the description was confusing. I was essentially saying, ignore the mockup since this applies to the future issue. And I didn't follow through with any designer afterward to get new mockups. So what I said in https://gitlab.com/gitlab-org/gitlab-ee/issues/2001#note_27829723 was technically true if you parse every line in the description. But I was lazy and the description was confusing.
I think your comments here (https://gitlab.com/gitlab-org/gitlab-ee/issues/2001#note_27769807) were in response to the comment thread previous and the description at the time. But since you weren't in the meeting, the communication broke down. And it appears you updated the description mockups based on the understanding we were using the new design in this issue. It wasn't communicated to you that we decided not to do that, and the description text that I had updated wasn't 100% clear.
-
Thanks for that background @victorwu. I'm not sure this MR directly addresses the issue. Not having the SSOT in the description of that issue seems like a symptom of not documenting what occurred in the meeting. I think the edits made in this MR are fine and good, but perhaps it is important to document in the handbook somewhere who is responsible for communicating what occurred outside of an issue (ie. in slack, in a meeting, etc.).
Here are a couple ideas for that:
- The PM is responsible for communicating changes to the feature.
- The persons involved in the meeting are responsible for choosing one person who will update the issue and ping relevant people.
Ultimately, a meeting should not be finished without a clear understanding of who will update the issue. I also believe the documentation should occur in a comment, not the description, so you can follow the history and it doesn't get lost in a giant issue description. Then, the designer is responsible for updating the description with designs that reflect the documentation.
The persons involved in the meeting are responsible for choosing one person who will update the issue and ping relevant people.
I'm not sure if it's documented or not, but this already happens (informally) most of the times. There are some cases, as the one indicated by @victorwu, where this didn't happen and some confusion took place.
