Right now, working and collaborating on design files is not supported very well in GitLab. Design proposals are available in issue descriptions and are shared and discussed in comments. It's not always clear which is the latest version. While we have the option to mark and comment on specific image spots in the blob view and in merge requests, the actual design collaboration happens much earlier in the process.
We need to try to determine what achievable MVC would look like that would provide the scaffolding for future iteration.
Problem
Issues are the single source of truth for planning features: the problem being solved, what the solution is, how it will work and what it should look like. Collaboration between designers, engineers and product managers is essential.
Currently it is hard to share a collection of designs/screens/mockups (markdown table) and impossible to leave comments on each image (e.g. image discussions in merge request diff).
There are other problems too, but these do not need to be solved in the first iteration:
handover from designer to developer (what is the final version)
Proposal
Manage assets designs
The first iteration should be the smallest possible iteration. Initially this means creating a new asset. In subsequent iterations it should be possible to upload a new version of the asset and archive the asset.
Comment on assets designs
If possible we should re-use the merge request image commenting feature. Subsequent iterations should also allow commenting on the image as a whole, like discussions on issues below the asset.
Linking to assets designs
We have issues (#), merge requests (!), epics (&), users (@) and we should have a quick way to refer to assets too. Not needed for the first iteration, but integrating assets into the planning merge request workflow is the primary way to increase visibility. It would be worthwhile to do some brief exploration of this.
@jkarthik@akaemmerle@sarrahvesselov I've scheduled this product discovery issue for %11.7 to plan the absolute MVC for the new ~"design management" product category. I'm hopeful we can ship this in very small iterations much like Epics.
@DouweM@andr3 I would appreciate your thoughts from a technical perspective of ways we can make the first iteration as small as possible.
Hmmm... what if the first iteration actually didn't even add a special assets interface, but just made it possible to upload images as an asset within an issue, enabling commenting in the issue. So there is no asset list, instead assets are created directly in the issue somehow.
add an Upload design asset to markdown composer
opens modal to upload file and give it a name, and then inserts a special asset link gitlab-ce%1234-1 (asset 1234, version 1)
when the comment is rendered it shows the artifact as an image tile, but clicking on it opens a view for commenting on the image
Next iteration might be during upload, allowing the user to create a new version of an asset that has already been uploaded.
And then we finally build an interface for viewing/managing assets outside of issues.
It's probably more complicated with more risk of going down the wrong path in terms of issue integration, but it sure would be a much more exciting first iteration
It's probably more complicated with more risk of going down the wrong path in terms of issue integration, but it sure would be a much more exciting first iteration
Maybe, I like this idea. It feels more iterative, adding just enough to build off of.
Biggest question I would have with this is how we display the comments about that image. One thought is that it could be in the form of our "start a discussion" model. The starting comment is the image, each subsequent comment is displayed as part of a thread.
Would you envision being able to attach comments to points on the image as we have in MR @jramsay?
Not sure if this is the kind of feedback you're looking for on this, but at my company we've found that an add-on for Sketch called "Sketch Measure" has been incredibly useful for the transition from the design to development process, in particular the plugin's Spec Export feature. It allows us to pull out measurements, colors, font styles, etc. without having to actually have Sketch (i.e. on Windows or Linux). Having something like this integrated in to GitLab as part of this feature would be amazing.
I think the main issue you bring is that NOT everything is code but it definitely SHOULD BE. Where I work this is our moto: everything is code.
We are trying very hard to have everything versioned into a repo, with the same branching model as we use, with a CI deploying review apps for easy testing and staging/prod deployment, with code review in merge-requests to help share knowledge and to catch issues, with release and version management, etc.
Yes we have to educate non-technical people on how to use git and gitlab. But surprisingly it is achievable. Technical savvy people are not too far to help and coach them anyway.
For example, we brought our redactors in by versioning and converting their assets in YAML - blog, documents, marketing emails, etc. We did it iteratively, one asset and one project at a time.
One thing we started to think about was how much we are unable to review changes in description field of an Issue. We cannot track its history as well - who changed what, when and why. It is especially important in the process of creating a solution - i.e. discovery and design.
You might see where I'm coming, but what if Issues were code - since everything is code? The great news is, Issues are already code because you can get a JSON document of an Issue from GitLab API so you could version it in a project with a CI.
Figure this: you have the discovery and design issue and at the end, what you actually deliver, among other things, is a bunch of Issues for every functional part of the solution. The definition of these Issues would be in a merge-request, in a project providing CI to "deploy" the JSON document of the Issues inside a project in Gitlab though the GitLab API.
The idea here is to apply the everything is code moto with the eat your own dog food mentality - maximizing the return value of all you created in Gitlab to help writing, managing, reviewing and releasing code.
I think a separate design asset visualization is definitely important. It separates what is standard imagery, and what is a design asset. Ideally, I believe the interface should simple interpret by file type whether it’s an asset or image. No need to flag it as an asset.
That said having the ability to flag might be useful to force something as an asset or not. A standard svg or png might want to be flagged as an asset.
It would also be extremely useful to link with design tools. Figma versions somehow being integrated with a Gitlab repo would be simply incredible, and offer great peace of mind that files are backed up outside of a single platform.
@DouweM@andr3 I would appreciate your thoughts from a technical perspective of ways we can make the first iteration as small as possible.
@jramsay Since we're talking versioning, comparing, and commenting, I can't help but come to the conclusion that these assets should be stored in Git, perhaps with LFS, so that we can reuse as much of our existing logic as possible. Every project could have project.assets shadow repo just like we currently have project.wiki. That increases the amount of work required for the first iteration, but would save a lot of "reinventing the wheel".
I think the way Phabricator does it (e.g. https://phabricator.kde.org/M140) is a pretty nice one to get started. I couldn´t find any reference to it in one of the other design asset issues.
I like @DouweM's input regarding a "shadow repository. Thinking ahead, I'm pretty confident that we will need to git version-control these (and additional design files) sooner or later.
If I get it right, this is about assets aka stable visual things used in your project like icons, design specs in a styleguide etc. "Design artifacts" like a wireframe suggesting a future design or variants of an UI might need a different workflow than assets.
@splitt3r (in regards to a separate asset space in phabricator) Initially I was also very fond of that feature of phabricator, however, I noted that it split the design feedback much away from the implementation. And in practice, e.g. the devs might notice a problem, or I as designer need to ask the developers something. So I started to paste the main mockup in a normal ticket and used slices of the image (made with a screenshot tool or in an image editor) to point out details.
One idea I came up with in the monthly ~Create call: can we store these design artifacts as LFS objects?
They don't need to be referenced in the repository, but if they're LFS objects to begin with, it makes it easy to pull them into the repo later.
We'd need to be able to prevent a given LFS object from being garbage-collected if it's being used as a design artifact, but not referenced in the repository. Something analogous to refs/keep-around/<sha> in the repository. This could probably just be an extra column in the database.
If we decide we need full shadow repository support later, we can easily split the relevant LFS objects into that shadow repo's LFS storage.
If I get it right, this is about assets aka stable visual things used in your project like icons, design specs in a styleguide etc. "Design artifacts" like a wireframe suggesting a future design or variants of an UI might need a different workflow than assets.
This is an excellent point @jdittrich1. I think this is about both at the moment, but I think it will eventually be split.
A big pain point for us (the UX Department here at GitLab) is having discussions around wires, mocks, etc. The threads become unwieldy, difficult to follow. Our original intention was to make these visual assets and the discussions around them a first class citizen.
This makes it possible to version requirements, decisions, and even designs (images attached to the description).
Commenting on images in issues
This makes visual discussions focused and easier to follow. These are also part of the solution discussion, so they should stay in issues (unlike Phabricator, which has an area just for assets and their discussions).
The “Attachments” tab and the image attachments have comment counters. New comments in images create system notes that deep-link to them. Multiple comments are merged into one system note (like description edits).
Possible enhancements: 1) Highlight unread comments in images; 2) Support uploading new versions, while keeping comments on older versions; 3) Support threaded discussions (i.e. replies to comments); 4) Support more file types, like videos and PDFs
One amazing thing GitLab could do is creating specs from popular UI design file types (e.g. Sketch, InVision Studio, etc.) making it easy to link from an issue. This is an extension from the rich links. However, I'm unsure where it fits considering the scope listed here.
As you might have already noticed, I'm pretty passionate about this. I'd love to be part of this ongoing discussion
In our discussion we were talking about a Design having multiple Versions, and each Version would have an ordered list of Screens, where each Screen is an image that can have image comments. This is useful so that a set of states/mockups can be uploaded and commented on as a logical set, and then a new version uploaded.
One interesting property of going the LFS route would be that perhaps each Design would have it's own directory, and perhaps in future a source directory could contain the source files that automatically generate the screens.
Thinking it through over the weekend, I am wondering a lot if it wouldn't end up being a lot of work to get to the first usable iteration if we built this on top of Git from day one. And that with all the frontend asset upload workflows, that we wouldn't end up with a nice mapping between design versions and commits, so we'd probably need a layer than allows version to be mapped to arbitrary commits.
In our discussion we were talking about a Design having multiple Versions, and each Version would have an ordered list of Screens, where each Screen is an image that can have image comments. This is useful so that a set of states/mockups can be uploaded and commented on as a logical set, and then a new version uploaded.
@jramsey I understood this slightly different when talking to @jkarthik.
I understood that there would be multiple Design Artifacts, those would consist out of Screens/Pages, every time a new image is uploaded for one of those screens a new version is created. Commenting happens on a version, this could either be generally on the image, or at a location.
@jkarthik is this correct? Could you share the mindmap you showed us yesterday? I think that will make it clearer .
Storage wise we're thinking a repository with a fixed structure. Having the files in a git repository from the get-go means we don't have to think about migrating possible large files into git later. We also get the versioning of files in a way we already know how to manipulate using Gitaly and comment on using diff notes.
I don't think the overhead of storing in a repository for an MVC is too big, we're already doing similar things for wiki's so I'm hoping we can reuse some stuff.
Initially, we're not planning on exposing the repository directly, as we're going to count on a fixed directory structure.
The shadow repository for each project could have this directory structure:
This means that we could easily store source files (sketch, psd, ...) in the future if we would learn how to work with those.
Ideally we'd upload the binary files directly to LFS, but this is not a strict requirement.
We'd have to keep track of this data in the database as well, this could map as follows:
graph LRProject-->|has many|Artifact["Artifact (folder in the repo)"]Artifact-->|has many|Screen["Screen/Page (A file in that folder)"]Screen-->|has many|Version["Version (a SHA of a commit)"]
Having these in the database will make it possible to use them in
other places: Rich tooltips, GFM references and so on.
@nick.thomas@DouweM any extra thoughts on this? Problems this setup
could not solve?
@reprazent@jkarthik thanks for sharing the notes. I think we need to start bringing this conversation back to an MVC in time for the summit.
I think there are a few questions that need to be answered:
What is the problem we want to solve in the MVC
I think the most pressing problem that we should try to address is the fact that issues should be the single source of truth during planning. The process of reaching the final design cannot easily occur on an issue, which means that until the design is agreed it is not often the single source of truth.
What is the benefit of using Git LFS for storage in the near term compared to object storage? What is the long term benefit, and the cost of migrating to a Git LFS storage layer?
I am not aware of any short term benefits, except perhaps that it may shape our approach to the data model.
Long term, I think the Git LFS is really interesting for versioning designs, and linking the designs that users comment on to the source file the designer users. But this requires much more than a repository to happen. To be useful, we need to start understanding the content of Adobe Illustrator files, Sketch files and the list goes on. I would suggest it might be more interesting to allow a designer to drag and drop a Sketch file onto a comment, and automatically export the artboards into images, before we implement this with a Git push. Git push without automatic export from the source file seems like an upload mechanism that wouldn't be used regularly.
Do we need a versioned data model in the first iteration?
I do not think this is necessary in the first iteration. Design management is an entire category that will need to support multiple features. Those future features may want this, but I think the features that would most benefit from a Git repository are not in the near future.
I would suggest that the smallest way to achieve an iteration that helps improve this is to support adding a "design" to an issue or merge request discussion. It would look a gallery of thumbnails, which can be opened and comments left on each image like image diffs (but not a diff). It would also be resolvable so that discussions about the "design" can occur at a higher level.
When a new iteration is needed, it would simply be a matter of creating a new design on the issue. There wouldn't need to be an explicit relationship between each design, except that live in the chronological discussion.
Add the ability to upload and order multiple images to a resovable discussion on issues and merge requests. This could simply be a convenience interface that inserts a table of images in the markdown interface. This would be a design and essentially emulates what we already have today, and what @jkarthik and UXers do on other issues already.
Add the ability to comment on the uploaded images like we do with image diffs. I think the challenge would be indicating when discussions were occurring on images without clicking on the images. This would be a significant UX problem.
This to me seems like it would be very helpful for improving designer/developer collaboration reusing many of the concepts we already have.
A more refined version of this would be, instead of using a markdown table of images in the resolvable discussion, we could instead include some kind of special string that is expanded into a gallery of image thumbnails (perhaps <namespace>/<project>/design/1 or some kind other shortlink). This get's us a structured data model that could then be refined an improved in the future.
TLDR: I tried to explain this proposal better in a video →
Problems
Design discussions are scattered alongside technical discussions.
Changes to design artifacts cannot be tracked in the discussion stream of an issue.
Overloading the issue description as the source of truth; using diffs to track changes to the description is not enough to track changes in static design elements; also impossible to tie discussions to these changes.
The designer is likely to share a user flow (journey/story) as a proposal in issues. The new solution must offer a way to see the changes in a user flow and allow discussions in the context of the designs.
Objectives
To enable design discussions in the context of the designs and in parallel to technical discussions.
To streamline organization and handoff of design artifacts between the designer and the developer.
Solution
In a project or a group, design artifacts are at the same level as issues and merge requests.
Design artifacts are a lot similar to issues. They have a title, description, reactions, labels, discussions, etc. similar to issues. What makes design artifacts different from issues are screens, versions, related issues and archiving.
A design artifact consists of screens that represent the user flow that the designer is trying to communicate. The screens are ordered to tell the user story and the designer can add an optional description (note) to each screen.
Changing a screen image, title, description, or removing a screen creates a new version of the design artifact. The designer can add an optional note when saving a version. This could be a summary of changes and can be used as the commit message behind the scene. In the future, we can implement image diffing between screen versions.
Discussions can be general to the design artifact or specific to the screen diff at a point of interest on the image. Discussions in a design artifact are resolvable. In the mockup above, each point of interest discussion is given a number. This is not the number of comments in the discussion. This number helps to keep track of the discussion between the sidebar and the screen.
A design artifact can be related to multiple issues and vice versa. This allows the flexibility for the designer to plan and design a user flow from a single artifact and later have many issues for implementation. Any change to the design artifact will create a system note in the related issues.
The designer can upload the source design file as part of a design artifact to maintain a single source of truth. In the future, we can implement ways to extract individual screens from the source file.
Design artifacts that are no longer needed in a project can be deleted or archived. Archiving can be the equivalent of the “closed” status in issues.
User flow: Creating a design artifact
A designer is most likely to create a design artifact from an issue page (similar to creating an MR from an issue page).
When creating from the issue page, the issue in context is automatically set as a related issue.
They can also create it from the “Design artifacts” list page at the project level.
The designer will add a title and description and start adding screens. They can add an optional note for each screen.
Once the designer is satisfied with the screens and description, they can save the design artifact thereby creating version 1.
The designer can ping other stakeholders for feedback.
What does an MVC look like
Create design artifacts as a new entity.
Allow multiple screens and discussions.
Future improvements
Allow versioning of design artifacts (screens and notes), archiving, labels, sources, confidential design artifacts, Reactions, etc.
This is to ensure that design solutions (and discussions) have a single source of truth and not get fragmented across many implementation issues. e.g. A user flow with say 5 screens might require more than one issue when planning the implementation.
Simply adding commenting ability to images shared in issues will not solve the larger problem of versioning the screens and user flow.
The designer’s user flow when using the design artifacts feature.
Terminologies used...
Design artifacts vs Design discussions
This is the source of truth of the design solution. At the same time, they enable design discussions.
Pages vs Screens
Pages is a common term in design tools (also web pages). Screens are more accurate and closer to what our users will design.
Not Archived vs Active
Issues are closed or open. Similarly, design artifacts are archived or active (not archived). I would love some suggestions for an alternative to “active”.
We are considering issue types as a possibility for incidents in incident management and well as vulnerabilities. It may be very similar here. If you have an object which has a lifecycle of being opened/created, collaborated on, and then eventually resolved/closed, you may want to consider an issue type. The benefits are that if you start with an issue object, you get all the existing functionality for free. The concept of an "issue type" is to allow different objects to extend that functionality to provide that native experience. From what I see here, a design artifact could fit well. Another benefit is that we can ship faster. What I see as the most compelling part of design artifacts is the ability to allow designers to work with visuals and collaborate with other people using visuals. Having all the existing features of issues would be great. You can tweak them slightly to fit your needs as a design artifact, and then really focus your innovation on what I think is awesome, the visuals part.
And to be clear, my vision of an issue type, is that you get a truly native experience, say for design artifacts. So for a design artifact page, the Create group can decide to customize it however they want in terms of interaction and visual design, but in the underling object model, it would still be an issue, and you'd have access to all those fields as needed. (And you would add additional fields specific to the design artifact issue type if you wanted to.) So for example, if you wanted to keep the comment/discussion thread, you could do so, but if you wanted to hide certain fields from the sidebar (or even not have a sidebar), you could do so. It would be up to the Create team to do that and implement it.
From an "issue platform" perspective, all issues would still appear in issue lists and issue boards. And I would expect to have issue type filters to help you manage that so you could focus on certain issue types.
And the Create team could even create/invent their own list views or other ways to manage multiple design artifacts. There is nothing technical stopping that. But the benefit here is that you already have these management screens to start off with and you don't have to implement them from scratch if you didn't want to.
@jkarthik tbanks for creating the video. It really makes things easier to digest and comment towards if it tackles a lot of content. I'll leave a few comments here, but keep things light.
Design discussion VS developer handoff
I think these are two different things and pose 2 different challenges. Thinking of them as such might help simplify and target problem spaces more specifically.
I can see they are ultimately connected, but at the same time, the iteration process of design discussion artifacts might be quite different from design spec artifacts. In the design discussions one might go from initial sketches, to wireframes, to high fi mockups changing tools as you go. For design spec artifacts I think its more common to stay with one tool and the interations might need tools that allow for a deeper inspection.
Sources and pages
Those too can be seen as separate I think (as you suggest it has to be in the beginning).
Often the work file is not suited for presentation. However, we can see these sources as mini design file repositories which provide anyone who wants to iterate on it with the required design files + able to share them again.
On another note, for design discussions pages themselves have value as well to show a history. Not thinking of a history per page, but as complete flows. Flow 1 which presents a few pages acts as iteration 1, flow 2 which has some edited pages and a couple of new ones acts as iteration 2. Similar to google docs versions or macos versions you would be able to go back and forth between them.
Separate entity
To keep discussions focussed I think this is great. At the same time I wonder about being able to keep an SSOT with an issue. How do we prevent from having to look in 2 different places in order to adjust the designs and or deliver for?
Having issue types for different issue stages, or even issue stage types (in which you can adjust an issue to change depending on what its goal at that moment is cc: @victorwu) might help with this.
Also, some page flows might be dedicated to one issue, while a more complete flow encompasses a potential future iteration
@dimitrieh : Your mention of issue stages reminded me that making allowing design artifacts be an issue type could be very helpful. (Although you might not be saying this.)
You could assign design artifacts to epics. And you could assign design artifacts to issues (once we have issues of issues, i.e. https://gitlab.com/gitlab-org/gitlab-ee/issues/2036). This makes it super helpful for the scenario where you want do any type of work breakdown structure. For example, you have a BE issue, have a FE issue, have a UX issue. So you could schedule a UX issue (which would be a design artifact) in advance, and then follow up with code implementation issues later. And of course all this scheduling / management would continue to live in epics/issue boards, and any other future ways we want to manage issues in general. I think this is pretty important because want to continue to have designers deeply integrated with the product development flow (i.e. organizing work, planning it, prioritizing it, scheduling it, etc.). But once you get into the details of actual design discussions and design artifacts creation, you can give designers their unique space to do so. (i.e. all the cool screens concepts that @jkarthik has designed here.)
If you were to create design artifacts as standalone entities, they wouldn't live in issue boards at the beginning, and you'd have to deal with annoying workarounds like creating a product discovery issue, but have it point to a design artifact separately.
To keep discussions focussed I think this is great. At the same time I wonder about being able to keep an SSOT with an issue. How do we prevent from having to look in 2 different places in order to adjust the designs and or deliver for?
This is a good point @dimitrieh . I think this is actually an argument for creating the design artifact features inside an issue itself. Perhaps a different tab (similar to merge request tabs) where you have the screens UI, or just a separate new UI, but still within the issue object itself. It would basically be a more powerful version of the asset library concept. (https://gitlab.com/gitlab-org/gitlab-ce/issues/19562).
With design discussions, they often bleed into other technical concerns or broader concerns. By having a separate design artifact entity, you lose that connection.
The downside here of course is that you lose that dedicated clean space of a design artifact.
To keep discussions focussed I think this is great. At the same time I wonder about being able to keep an SSOT with an issue. How do we prevent from having to look in 2 different places in order to adjust the designs and or deliver for?
I think that could be the the last version of a design, we could allow linking to versions as well as the current version. So in an issue we could link the "current version". That always remains up to date.
@jkarthik I think I mentioned this last week, but I don't the term design artifacts is ideal because the meaning of artifact isn't obvious to me in this context. I also think it is contributing to a problem definition that is too broad for the MVC.
To enable design discussions in the context of the designs and in parallel to technical discussions.
To streamline organization and handoff of design artifacts between the designer and the developer.
I agree with @dimitrieh that these are separate problems. As mentioned above I think the problem that we should address first is a better way to share and discuss designs on issues.
@jkarthik@victorwu I'm quite interested in seeing where we can go in the first few iterations without creating a list page. If we treat designs like issues I really concerned that we'll end up with a more things that need to be labelled, linked and added to milestones and I'm not convinced that we need this. If we go down this path early it will seriously change how much an issue is a single source of truth.
My other thought is that we need to avoid a waterfall model of stages.
this is spot on – design and development should be better/more integrated as a result of this change, not partitioned into separate areas of the application. I don't want extra lists and boards to check to know what is going on.
One example you mentioned @jkarthik is that there are larger design projects that will be implemented over multiple issues. But any design project that needs to be implemented should consider that implementation in the early stages of the project. Why couldn't we just use an issue with some designs on it (assuming we've added commenting and some kind of iteration capability)?
Also, with reference to relating issues and designs, I think relating the same design to multiple issues isn't the easy solution it might first seem. If a design is to be implemented over multiple issues, it is actually really important that each issue have it's own designs that show specifically what will be implemented, independent of the other issues, so that anyone looking at the issue can quickly see the scope of the issue, and what the end state will be.
Linking to specific versions of the designs is unlikely to be the solution here because a large design project typically looks at the big picture, then iterates, and then breaks it down into smaller changes. That won't generate nice bite sized versions that show the specific changes to implement.
I'm not sure what the ideal solution would look like
@jkarthik@victorwu I'm quite interested in seeing where we can go in the first few iterations without creating a list page. If we treat designs like issues I really concerned that we'll end up with a more things that need to be labelled, linked and added to milestones and I'm not convinced that we need this.
@jramsay : Are you saying that you think it would be burdensome to have the design artifact (or whatever you call it) object have fields like labels, milestones, etc.? The benefit with considering it being an issue type is that you could choose to hide these fields from the object page itself. (And I think just hiding on the rendered object page is a pretty low-effort solution, versus building out the desired parts you want from scratch.) And later on if you did want to open up the label field (or other originally hidden fields) to be used by users, you have that option.
Also you do get things like commenting for free, which you do want right? In @jkarthik 's designs, I see that the commenting design is off to the right. What could be interesting is that if you do re-use commenting and treat this object as an issue type, you could reuse all the BE logic for comments, but have the comments be displayed in the way you want them to be, off to the right. In fact, the object page could totally be visually re-designed compared to an issue. But you can still leverage the BE object model benefits of being an issue type. It seems that right now from looking at the designs, the obvious things are title, description, and commenting could be re-used, with I think commenting a pretty big deal since it's really powerful. (Don't forget things like notifications and markdown and all that.)
In terms of issue lists and issue boards, by having this new object be an issue type, it would automatically show up in these places as an issue. It could be a plus or a negative, depending on your intended designs. I was thinking that these new objects would also need to be work-managed. So I thought it would be a plus: See https://gitlab.com/gitlab-org/gitlab-ce/issues/53587#note_126220962. But if that's not the intended design, then having these objects be in these places may actually clutter up the views. You could have issue filter types mitigate that. But that may still be a poor experience nonetheless.
If we go down this path early it will seriously change how much an issue is a single source of truth.
Not sure what you mean by issue being a single source of truth here?
Are you saying that you think it would be burdensome to have the design artifact (or whatever you call it) object have fields like labels, milestones, etc.?
@victorwu thanks for explaining – I was responding to the proposal by @jkarthik which did include labels, milestones etc.
Not sure what you mean by issue being a single source of truth here?
@victorwu at the moment designs for a feature are included on the issue in either the description or in the comments, which means I can just go straight to the issue and see all the information about it. If the relationship of designs to issues were like that of epics to issues, or related issues I think it would become a confusing mess of links to find the correct designs, and split the conversation across multiple locations.
@victorwu@jkarthik Here's a more visual workflow oriented description of the direction I'm trying to describe:
When a product manager, designers and developers are collaborating to build a feature, they can upload a design to the issue consisting of one or more images. They'll appear in the discussion feed chronologically like other kinds of discussions do. Discussion related to the design can occur as:
discussion on the design as a whole
point of interest discussion on the images – this might be accessed from a view similar to @jkarthik wire frame.
Once enough feedback has been provided, the designer can upload a new design to the issue which will automatically become the next version of the design.
More specifically, from a users perspective (I am not specifying the data model):
Designs are accessed through an issue, which means:
Designers and developers work together on the same issue.
No labeling, milestones, parent-child, related designs or other management overhead is created.
Anybody reading the issue will have all the information they need, they don't need to be linked to a design in a separate area of GitLab.
Issues only have one design*, which may have multiple screens and multiple versions.
This means when a designer is working on an issue, they simply upload new screens to create a new version. This might automatically resolve/collapse previous versions to reduce their visual space on the page.
To restate what might have been lost in my longer comment above, after building this feature designers and developers should be more closely integrated and able to better collaborate, not partitioned into separate areas of the application.
I like this idea of gearing towards smaller primitives. Instead of a new object, just a new comment object.
I do still think that an overview of the progression of an issue's design, decoupled from the general discussion, is helpful. So a tab inside of the issue similar to changes tab in a merge request would be great, though not needed for the MVC.
In the original proposal there are a few untested assumptions:
Designs can transcend issue concepts. Meaning if tied to an issue they are limited.
Designs should be manageable independently from issues as to improve discoverability and reusability.
I think both of these assumptions have some truth to them, but nothing that is not possible anymore after implementing a new type of comment type/object dedicated to designs.
Thanks, everyone for all your feedback! I think the most important piece of feedback that I can take from all this is to prioritize which problem to solve first. After a call with @jramsay, we've decided to narrow our focus on enabling design discussions inside issues. This will have immediate benefits to our users. I'll keep iterating and will share more detailed mockups soon.
What is the benefit of using Git LFS for storage in the near term compared to object storage? What is the long term benefit, and the cost of migrating to a Git LFS storage layer?
Using Git storage (a shadow repo, not necessarily using LFS in the first iterations, though if the abstractions allow it, we should use LFS) in the short term gives us the versioning from git out of the box. I'm not sure we need to expose the versions in a first iteration, though.
I do think that implementing a shadow repo (possibly reusing a lot of stuff we have for wikis) would be the easier solution over implementing something based on DB records with files attached, and then migrating that later. As I got from the importance of versioning, we would have to do that sooner or later.
Since most of this feature would revolve around conversations on images that change based on those conversations, I think it also makes sense to try and reuse some of the existing DiffNote logic we're currently using in merge requests rather than re-implementing that.
@zj What do you think of adding another git repository to store designs from a Gitaly perspective? Storage wise I was imagining something similar to wikis: where we put a .assets repo next to the existing project and .wiki repository. That would give us access to all of the functionality for creating & updating files we already have in Gitaly, right? Or am I missing something that would make this more work than I'm thinking?
*Excuse my ignorance to this issue if I'm repeating things already said (brand new to it and this feature)
@jkarthik I just watched your Feature proposal: Design artifacts video and I have a few notes regarding your feedback ask:
Making design artifacts a separate entity
You mentioned you thought long and hard about this, but I'm curious if you've had a chance to chat with a developer knowledgeable of the code/implementation of issues? I ask as they might be another valuable resource to help inform this decision. My gut says (assuming there are core needs that exist in issues, but are limiting in the context of design artifacts) design artifacts could extend (in the programming sense) issues and potentially live in the existing issues ecosystem. Not advocating for this exactly, but pushing toward it from the lens of adding a new row "section" to each Project's navigation UI when a design artifact may be a special superset of an issue.
Terminologies
I agree with the lean toward "screens" over "pages" since AFAIK 99%+ of projects leveraging GitLab are in fact software projects that if contain a visual UI are consumed on screens. Another idea may be artboards or canvas, but I think screens is strongest.
I think "Active" works here in opposition to "Archived". Maybe "Open"? Maybe a specific term isn't even necessary where it's archived or not.
I think this is a really promising idea, nice work to you and everyone involved!
I think that versioning for design assets, stable, ready-to-use, file-equivalents makes sense (a lot!). An design asset e.g. would be an icon as svg.
I think that (conventional) versioning for designs itself does not make sense. An design here would be the file in inkscape or illustrator of which the *asset" is an export, but it will contain far more: comments, swatches, alternatives, scanned sketches…
The actual work of a designer happens in the "source" document, not in the asset. For versioning this is particularly important, I think. The design "sources" often show several alternatives in parallel. They could be seen as versions, but they are not merely legacy.
Old parts are juxtaposed with new ones, used if great, deleted if they do not work and shifted away from the center of the canvas if they are interesting, but can't be used right now.
So instead of the linear/branch structure with distinct versions, there are multiple, parallel, intermixed representations in design work. One can press design work in a development like structure (and it can make sense) but it has good reasons why designers work that way and translating it in a like-code-way has its problems.
@jramsay@jkarthik Maybe a future iteration adds a central place to view all of the design discussions, but having the design discussions in issues is a must. Even today, issues are the central place for all discussions that make up a feature/change: technical, visual, interaction, copy, etc. And everyone participates on those discussions, not only designers, but engineers, PMs, users, customers, etc. So it makes sense for us to start there, with what we know and where we go to.
This feature's current scope is essentially commenting on and versioning images. But this is not only about feature proposal designs, it can also be used for bugs, or sharing examples/competitive analysis. Don't get me wrong, this is just a heads-up as I believe it's reasonable for us to start with the “design” approach (because we are confident about this use case) and later on evolve it (armed with the necessary information).
@jramsay@jkarthik I want to elaborate on a point that highlights users and customers: permissions. Because everyone can contribute, everyone should be able to add their “designs”. I'll definitely use this feature when creating a feature proposal issue, so why shouldn't community members? I think we might be overthinking this permissions aspect, where the really important thing is to prevent overwriting someone else's designs.
@jkarthik how can we make this a seamless experience and for users to easily know about and use this feature? I think there are 2 aspects here: consuming and creating design discussions.
Consuming: As you showed on today's call, having “system notes” in the “Discussions” tab is really important to make sure everyone's up-to-date on the “design discussions”. That addresses this aspect.
Creating: Would one always need to go to the “Designs” tab? Would it be possible to somehow integrate this feature in the comment area? That's one of the reasons why I previously suggested having an “Attachments” tab, so any attachment would end up there, without users having to navigate to a specific tab that they might not know of. I'm comfortable with not having everything decided now, but we should at least explore this. Some crazy ideas:
Switch between “add comment” and “add design” mode?
When attaching an image, the image is added to the “Designs” tab with the image title? E.g. using our Markdown notation .
Change the “Attach a file” icon to something resembling a generic document and add a new “Add a design” button next to it?
@pedro I explored (as you suggested) adding a button near the comment form to help users discover this feature without switching to the Designs tab (mockup). I'm not sure about this approach since this button could be associated with the comment form, which has nothing to do with adding designs.
@jkarthik my idea would be indeed to associate the comment form with adding designs, that's why I suggested placing the “Add a design” link/button next to the existing “Attach a file” link/button. My point is avoiding switching to another tab just to add designs — which can be hidden away and not much visible to users.
You can find the designs and the rationale behind the decisions at the following links. […] Also, look for the little blue dots placed on the mockups (tour points). These will walk you through the design, focus attention on key elements and provide design rationale. […] It would've been nice to share these designs directly on GitLab, using comments on images.
Folks: Image diff discussions are a feature we implemented a while back. https://docs.gitlab.com/ee/user/discussions/#image-discussions. It was our first real attempt at making first class features for designers. I don’t see it getting much use by GitLabbers and if you don’t know about it, that’s an indication where we haven’t done a good job.
I’m pretty convinced that our concept of discussions on an image diff is not a compelling enough use case. Having designers or whoever review images during the implementation phase of a feature is okay, but not the most interesting use case for designers. I think designers are really heavily discussing and collaborating during the ideation phase. During the implementation phase I think it is more about review, so actually image discussions are helpful but not super value additive.
I wanted to bring this up for two reasons. Number one: We’ve considered the more general problem of helping designers before and let’s take lessons learned from where we haven’t been successful yet. Number two: I think the interaction designs of image diff discussions are pretty compelling in themselves and I think it’s a shame they don’t get more use. I’d highly recommend folks try out the feature more if you haven’t already and see how they intersect with much of @jkarthik’s ideas. @dimitrieh did a really good job designing those interactions, based on my little usage of the feature, and I think we can learn a lot about it and apply those learnings, since it’s already a real production feature.
@victorwu I think the actual functionality and implementation of image diff discussions is great. From my perspective, the main reason why this feature is not leveraged more is mainly because it's available in merge requests and commit details only right now. I'm sure that having it available in issue discussions would change usage drastically.
Notes I wanted to add from the meeting and to react to comments above:
Being able to pinpoint specific points in an image is very worthwhile, though maybe not needed as a first MVC. Per screen, discussions would be a great first step as well.
When implementing image coordinates, we might want to think about making it more flexible. In merge request image diff discussions, discussions can only be tied to one coordinate. What if you want to reference multiple points? Perhaps a solution is there with something like clicking on the image which copies the coordinate to the clipboard in a way that markdown understands. After the coordinate gets submitted in the markdown the coordinate is displayed permenantly on the image.
In terms of access, I think friction should be kept as low as possible. Anyone should be able to suggest changes and come up with designs/screens if necessary. However, we do need to have some kind of management of leading version (similar to master branch vs feature branches).
Almost identical image diffing is indeed more suited towards implementation discussions than towards design/ideation discussions. Different versions per flow (multiple screens) would be enough so we can revert and change direction when needed in order to define leading design versions.
Displaying versions and identifying the leading version would be great to see in a graph potentially similar to fork network graphs (future stuff though)
In terms of an MVC, it might make sense for the BE to already prepare for future functionality, but in terms of UX/FE to keep it light and simple and creating as little overhead as possible. @jkarthik I haven't seen what your latest revision looks like as I was on mobile in the meeting, but see if this corresponds what you had in mind for an MVC. Basically the idea of https://gitlab.com/gitlab-org/gitlab-ce/issues/53587#note_126324121. Here are some rudimentary screenshot adjustments:
Only the author of the discussion can drag and drop images in
Screens can be focused in on and switched between
These discussions can be resolved, hiding them including the image almost completely
We could gather all these kinds of discussions potentially in a design tab where you could see a progression of some sort :)
This does not tackle per screen or coordinate discussion yet though
Thanks for all the feedback everyone I've drastically simplified the proposal for an MVC.
Data model
Design
image
file name (not editable)
order
Version
Consists of many designs
Adding, removing, replacing or reordering designs will create a new version
The user can add an optional note when saving a version which helps to start a discussion. The designer can use this note like a changelog.
Designs tab
Design tab
Select and Remove
Versions dropdown
Pending changes
Add note and Save
Discard changes
This new addition will show a thumbnail grid of all the designs associated with the issue.
Developer+ members can add, modify, remove and reorder designs.
When adding new designs, based on the file name, older designs are replaced.
In the future we may add more metadata (like title, description, etc.) for each designs.
Design detail modal
Empty state
With discussion
Discussions
When a new version is created
Started by a user
These screens will give a general idea of the feature. These may not be fully polished designs. Also, the responsive versions of these designs are pending. I'll tackle these when we are heading for implementation.
@jkarthik I like it and the flow makes sense. The only thing I'm still concerned about is the path to get started with this feature. We need to think about how users get to know this feature. Some ideas:
Have a “New” badge next to the “Designs” tab label to highlight this new feature. It would go away once users visit the tab the first time — we also need to have a good empty state there.
Suggest using the “Designs” feature when the user (if Developer+) attaches an image file to a comment.
Some other questions:
Does clicking on the “Add designs” button trigger a file upload field?
How can users reference a design in regular comments?
In terms of polish, I know these are not final designs, but just some remarks that might help you when you get to that:
In the design tab, the discussion filter (activity/comments) is missing.
For the versions dropdown, looking at our dropdown specs, we don't have any variation with the checkmark on the right side.
In the design detail modal, visually the dark background doesn't work very well with the light topbar and sidebar. Maybe if the background is a light gray or the topbar is dark it can visually work better.
What do you think of adding another git repository to store designs from a Gitaly perspective? Storage wise I was imagining something similar to wikis: where we put a .assets repo next to the existing project and .wiki repository. That would give us access to all of the functionality for creating & updating files we already have in Gitaly, right? Or am I missing something that would make this more work than I'm thinking?
@reprazent Nope, you're completely right. And it's quite easy from a Git storage perspective. That is, if you'd want to store assets like this in a git repository. The delta's are rather large so the repository size will be large. But as a first iteration it might be a good idea and quite easy to develop.
Based on @jkarthik I'd adjust the datamodel slightly, so we have a model describing a collection of designs. That way we can link that collection of designs to an issue. But we aren't stuck there, and we could also link it to something else (for example Epics). And we could use DiffNotes for storing the conversation about the in the designs.
So the data model in the database might look like this:
graph LRProject-->|has many|DesignCollection["DesignCollection - A collection of multiple designs(folder in the repo)"]DesignCollection-->|Belongs to|Issue["Issue - The issue the discussion is taking place on"]DesignCollection-->|has many|Design["Design - Screen (A file in that folder)"]Design-->|has many|Version["Version (a SHA of a commit)"]