How do you annotate design changes to your dev team?

over 5 years ago from , Product Designer

Hello designers!

I am looking to improve my design process and some tips and opinions from you would be amazing.

There is always one pain in my process that keeps me annoying over and over.

Let's say I sent a design to devs for them to start coding it. After a while I have to change something in the design, based off some feedback or after metrics come in. I then have to go over all my design decisions and changes again to list them out for the devs. Either in person or via GitHub issue etc.

But I find this quite frustrating - going back and annotating everything manually. Especially when small changes (like copy changes, slightly changed color shade…) are overlooked and don't make it to the final release - it's extra annoying. I'm I alone in this?

How do you communicate these design changes to your dev team? If you do it manually, any tips to make this less painful? Do you use any tools or frameworks for this?


  • Paul Gates, over 5 years ago

    A few direct suggestions:

    1. Discuss this issue with your team. This is a team process, and they should have some input on how you work as a collective.

    2. For small changes, work out a process with your team that allows you to review a build before it goes out. You should have the ability to hold a release back if you don't think it's ready. Document anything you'd like fixed, prioritize it as a team, and focus on a few things at once. Be flexible.

    3. Larger changes should not come as a surprise to your developers. Get them engaged in the feedback and your rationale before you run off making decisions on your own. This way, you build trust and help to maintain focus on important UX issues for your team.

    Lastly: tools, frameworks, and process will never trump a good relationship with your team. Making collectively agreed upon design decisions via communication is your most important job. The little details that annoy you will be much easier to address if your team trusts you and your process is focused.

    11 points
    • Jan Vu Nam, over 5 years ago

      Great comment Paul! Thank you! Nothing beats a good and enthusiastic relationship with your dev team, agreed. Still the documenting part can be greatly automated. As designer, I tried to visualise the solution over this weekend.


      Do you think a tool like this could help in way or do you think it's not necessary?

      0 points
      • Paul Gates, over 5 years ago

        Very hard for me to say. As I suggested, it's up to you and your team to iterate on what works best.

        In theory, an automated process that spits out diffs in design files at the right level of granularity could help your workflow. An integration on top of that with task-tracking software would be the obvious next step. That said, for me, this issue is mostly solved by having a focused, iterative working style with my team.

        0 points
  • Johan Ronsse, over 5 years ago

    What I am about to suggest might not work for you, but I will explain how we deal with it.

    As designers we observed the problem you describe.

    Instead of just delivering static mockups, we have changed some of our processes entirely to a) include front-end development template delivery (for web) b) have access to the native codebase.

    If you want to change the spelling of a word, it doesn't make sense to go send an e-mail about it. Just change it in code and send it out for approval.

    This way the design change is embedded in the single source of truth (i.e. the app code) and it can't be missed.

    I realize this involves designers starting to code and it might not work for every type of change, nor do we want any (starting) designer to have access to any codebase (that has to be stable), but in general I think designers, especially senior UI designers, need to move closer to development sometimes so just avoid some of these communication problems entirely.

    2 points
    • Jan Vu Nam, over 5 years ago

      Interesting! Thanks for the answer Johan!

      I see 2 downsides of this approach and am not sure how you tackle these in your team. As you said, may not work for my purposes, but still would love to hear how you deal with it:

      1) The design source of truth is lost - there will be discrepancies between the design in the design file and final product, and it is easy to lose track of what changed for what reason. It harder to work with the design files afterwards if they don't really correspondent with what is in the product.

      Or do you have some special ways to keep the design file 1:1 with your codebase?

      2) It takes time and focus away from the designer - even when the changes are small, it takes time to communicate changes to the developer in person. It also leads to "designing on the go" syndrome - where designer is trying different styling variants with the developer rather than in his design tool. Which can make this process much more inefficient, considering how each run has to be committed and built out from the command line.

      0 points
  • Andrew C, over 5 years ago

    Sprint demos. A squads dev lead, pm and design (or a combo of these, but ideally all) need to show their work every week. You critique and write polish tickets in JIRA for them. Then at the next demo for this project the changes that happened or didn’t happen are apparent and able to be discussed as a team.

    This keeps feedback mostly about what you’re actually releasing (design mockups are useful but always a best guess as to what the future will be), it puts the team through the fire together and builds camaraderie, and it keeps decisions visible.

    There’s a few things you need to enable demos: agile and OKRs, a focus on outcomes and not release output (if a feature isn’t done and you need extra time that’s a success not a failure), be comfortable having dev and pm design alongside you (this is agile btw), and you need to structure direct feedback so it isn’t just a barrage of negativity. I like to use the positive/negative/questions/ideas framework to structure feedback.

    1 point
  • Emile-Victor PortenartEmile-Victor Portenart, over 5 years ago

    Hi Jan,

    Here in at our Team we work with Trello but the issue is the same. As a designer I want to communicate to my dev in a way that he's going to listen to it and do the fix, especially if it's an easy one like copy/change an illustration/new style for a button etc etc.

    For your developer to see it and listen to it, I think the best place to in his Github via github issues. I use www.marker.io to capture a screenshot, annotate it and create in 1-click a Trello card ( you're going to do a github issue ).

    Your dev will see that issue with a clear screenshot, the url of the page where you want to make the change, some browser information and you can even attach a new design if you want.

    I think that's the easiest way to be listened by your devs if you can't fix these small glitches yourself.

    Also, I may be a bit biased because I'm the founder of Marker.io :-)

    1 point
    • Thomas Michael SemmlerThomas Michael Semmler, over 5 years ago

      an easy one like copy/change an illustration

      I wanna highlight something real quick, never assume how difficult, time consuming or painful some task for a dev will be. Because just changing a picture, could be very painful, lets see how this could be:

      • your image is an actual img, it needs an alt attribute. It needs to be translated, translation takes time and costs money. You change the image halfway and ne alt needs to be different too, it messes it all up.
      • your image is an SVG, embedded directly in the document, the backend application might not have the capabilities of loading SVG to directly import it, so this needs to be done too.
      • your image is 350*90 px wide, but it also needs to be 2x, 3x, and 4x that size and you forgot to provide it. Also, it will look awful on mobile, so you need to also provide a different image to be used in the picture element. Also at 2x, 3x and 4x. And it needs alt attributes of course as well.
      • your image was an SVG, embedded directly in the document and it needed to be interactive or animated. Why changing this is time consuming is hopefully obvious.

      there can be tons of reasons for why this can be a tedious task.

      I want to communicate to my dev in a way that he's they're going to listen and do the fix.

      Developers are not monkeys. They enable your designs to turn into actual experiences. There is probably a reason for why it seems like they are just not listening .

      But I totally agree in essence with what you are saying, that is that communication is essential, without it it won't work well.

      7 points
      • Marvin Hagemeister, over 5 years ago

        Developer here. Thank you so much for your comment. I've pretty much encountered well the problems you listed at some point in my career. We usually have to interface with adding legacy systems which have weird constraints like that. It's often out of budget to fix those.

        Communication is indeed key for a smooth collaboration between design and development. Nobody likes being treated as a monkey. Mutual respect goes a long way.

        1 point
      • Emile-Victor PortenartEmile-Victor Portenart, over 5 years ago

        Thank you for correcting me! I want to apologize as I didn't want to sound bad against developers but I can see now that it could have been misinterpreted.

        I'm happy that you found out that in essence, I wanted to point out an issue in the communication flow as I think it's the most crucial part and most of the time the most broken one.

        In our team, I found out that the best way to help move the product forward is to work with the strength of everyone. That means as a designer I'm also in charge of the frontend to help the developers focus on difficult backend challenges.

        Have a nice one!

        1 point
  • Jan Vu Nam, over 5 years ago

    Thank you all for your amazing answers! I am overwhelmed by the amount and quality of the replies I got from you guys. Good job!

    Apart from few interesting tips, most of you still seem to annotate design changes manually. Doesn't matter what tool, but it seems like most of you still go back and document the design changes on your own. Either in some annotation tool or as comments on changed elements - but the problem is still there - you get distracted from the creation process to document things you've already done.

    I believe there is an opportunity to complete automate this documenting part. Imagine you upload two versions of the designs - one older and one newer - and the app automatically tells you exactly what changed - down to the layers level.

    I tried to visualise it during the weekend: https://cl.ly/rhmK/

    Would something like this make your life easier? Or do you consider the problem so small that it's not worthy solving? (inserts forever alone meme).

    0 points
  • Artur Eldib, over 5 years ago


    0 points
  • Aloke Pillai, over 5 years ago

    We are working on this problem at usepastel.com - happy to answer any questions you may have aloke@usepastel.com

    0 points
  • Matt WelchMatt Welch, over 5 years ago

    Talk to them. Don't just send documents in hopes that they complete all the needed changes. Real world chat gets you there way faster and builds rapport with your dev team.

    0 points
  • Alex Hazel, over 5 years ago

    Currently, I am doing it manually in Photoshop with SpecKing - http://wuwacorp.com/specking/ - Looking to improve this process with new tools though.

    0 points
    • Aloke Pillai, over 5 years ago

      I would suggest Zeplin.io in the design phase & usepastel.com in the web phase.

      1 point
      • Jess EddyJess Eddy, over 5 years ago

        Hey, curious: what does Pastel do that is unique? What value does it offer outside of Zeplin? I've never used it, thanks!

        0 points
        • Aloke Pillai, over 5 years ago

          Hi Jess! Pastel lets you comment on live websites and collaborate on feedback with others. Zeplin helps document how to execute a design.

          0 points
  • Thomas Michael SemmlerThomas Michael Semmler, over 5 years ago

    Let's say I sent a design to devs for them to start coding it. After a while I have to change something in the design, based off some feedback or after metrics come in.

    I develop everything I design myself, so that specific thing is not a problem, but in our team we do have a clear rule about design phases. We have four of them and many people take part in them, including stakeholders and developers:

    • research
    • planning
    • visual design
    • implementation

    We don't allow ourselves to go into any phase, unless the first one is done. So if you have to change something in the design, based off some feedback or after metrics come in, then your research phase was not done yet.

    • In research, you gather metrics, ideas, loosely defined wishes and goals for what you are supposed to design.
    • Then in planning, you allocate, gather plan all the resources you'll need, from design to implementation. This is also the right phase for low fidelity design work, like wireframes and prototypes and to gather last decisions that have big impact on the visual design phase.
    • Following visual design, where you actually sit in front of the program of your choice to create mockups that show how the final product will look and feel.
    • and of course implementation itself. Where you... implement.

    If you honour the boundaries between design phases, then there are no questions unanswered when implementation happens.

    Your Situation shouldn't occur, because if you don't start designing until you have all needed information, then there won't be any implementation that needs to be cancelled. Vice versa, when implementation has started, don't design anymore. It is done. Do not start development unless design is completely done.

    The only thing that won't make this process painful are barriers and respecting them. A clearly defined process can be a guideline for all and prevents conflicts and frustration from arising.

    0 points
    • Jan Vu Nam, over 5 years ago

      Thanks for your lengthy comment Thomas! I appreciate the effort!

      In the ideal world - yes, this should be the practice. Sadly, in the world or startup hustle, things can and do change very fast.

      Especially when your team is working on one particular product, you will never be really "done". You can never see all the cards in the deck at the start, and some things you simply don't learn until some real users get their hands on your product.

      It's a classic iterative design mantra - Plan - Prototype - Feedback - Implementation - Evaluation - Plan …

      It's simply necessary to keep growing your product, and there will be no perfect research or a masterplan in the beginning that will guarantee you a unicorn in a first go - but rather years of carefully listening to your users and delivering.

      That sometimes means changing the design too… in smaller or bigger ways.

      0 points
  • Derek Rudd, over 5 years ago

    I agree with Paul. I would like to add that i upload the changes to Zeplin and then leave a comment for them before i walk over and talk to them.

    0 points