Commenting on designs in issues

Welcome to Tanuki Tuesday, where I look at the features offered by GitLab. This week I look at the ability within GitLab for users to comment on designs within issues.

This was a feature I came across by complete accident, but I am glad I did. It is something which doesn't make for a long post, but does make collaboration on issues a lot easier. It also highlights that GitLab is not just for developers, but for the whole team; designers, developers, testers, managers. Anyone who is involved in the process can use GitLab for their own needs.

Disclaimer for anyone worried about the privacy of people who are listed on the designs, the images used as the "designs" in the article are taken from the GitLab Press Kit.

Adding designs to issues

When starting out with GitLab you might spend time looking at issue templates and ensuring each template has a space for designs to be added into the markdown so it's all rendered as part of the issue description when you. That might work for you initially - after all, the images are fairly large on screen and can be clicked on to open them and make them full size.

But what happens when someone has a question about the design? If I asked the question "Should the Security Dashboard link display the project grade?" which "security dashboard"  one do I mean? I have to be absolutely clear in the wording for anything which could relate to multiple things on the screen. When it comes to things which can be interpreted differently by different people (think of some bizarre version of ink-blob tests) that can lead to confusion.

Fortunately that doesn't need to be the case. Once an issue exists there is a section below the issue description to upload images. Just drag and drop them in, or click to open the file explorer to upload.

The focus of the description is then to describe the issue, requirements, outcomes, odd edge cases and other information. Designs are separate.

Collaborating within the design

Now the design has been uploaded to the issue, clicking on it opens the image to allow discussions to take place, without needing everyone involved to be around the same table, or on a call.

Going back to the earlier question about adding the security grade to the Security Dashboard link, it can be articulated by clicking on the desired link and then adding the comment.

Each new question point starts its own thread which keeps discussions grouped together and allows the discussion to evolve the design when people have the time to work on it. It also means there's not a need to think of every possible question you might have around individual items ahead of a single meeting on an issue. Best of all, any decisions and direction are already documented as part of that discussion, so there's no need to have a follow up email with what has been decided.

But my design team don't use GitLab!

Okay. If getting them to use it isn't an option, there's no reason you can't still use the feature. Create the issue, add the design to the issue, and let the development team review it and add their comments. That way if there needs to be a meeting with the design team about certain aspects, not everyone is going to need to attend. Everyone's feedback is collectively available for a single person to take into the meeting to allow others to carry on with their other tasks.

Working in this way has the added benefit that everyone can see questions others have had, and it might raise additional questions in their mind which can be added. This might not be possible in the flow of a meeting, meaning questions go unasked or unanswered.

Ah, we already use that kind of feature in tool X

Yes, this ability exists in other places (Google Drive, Invision etc.), and might be used by your organisation there. But is that then fed back into your GitLab issues? If not, then you're forcing your developers to look at an issue in GitLab, then go and find the design which matches the one on the issue in another app, then digest the content. That takes them further away from their work. It also means that come testing time for an issue, any decisions which have been made on the design aren't transparent and available against the issue which is to be tested by the QA team.

Conclusion

The ability to comment and collaborate on designs within issues is one of the features which shows that GitLab is for more than just developers. Even if you use similar tools elsewhere, you should make sure any decisions which have been made for designs are also brought into GitLab on the issue so it is the single source of truth for your development team, and others who do use GitLab.