8

How do you manage Design Documentation of sketch files and handover to development?

almost 5 years ago from , Lead Experience Designer @ Softvision

Hi community,

Do you ever needed to make advance documentation of design made in Sketch? If yes, how did you do that, what tool did you used?

I'm currently working on a complex design system and I need to find a way to properly handover the design and the documentation to the BA and Development team.

I also have the following needs: - should somehow integrate with Confluence or Jira in some way or to provide links to the flows documentation. - the flows will change with iterations but the links to the documentation should be the same and automatically update what was changed - should have the preview of the page / template and the information notes for it. The notes should include the current page details but also how it integrates with the flow so it might be helpful to add links to other page documentations from the flow. - it should somehow integrate with the components specs - facilitate the specs or provide links to Invision Inspect / Zeplin.

What is your process and how do you manage this need?

Thanks,

11 comments

  • Thomas Ruehr, almost 5 years ago

    Hi, First time posting because this post struck a chord with me :)

    Regarding the integration to Jira/Confluence. It just will not work how you want it to, We tried for a couple month it was just a hassle. You will not be able to have web previews that are version controlled directly in confluence using Sketch.

    I'm sorry but what you want to does not really exist for sketch. The beauty of figma is it's web embed. Really gorgeous for documentation on Notion.

    But there are tool available that works for us.

    The way our system is divided:

    • Notion (confluence works) for user stories, macro design specs, user persona, etc. But also a "one point" of entry for my PM. We have detailed pages for every area of our product with links to flows, page layouts, and component specs.

    • Abstract for design versioning, components and page handoff (decent inspect feature) and design presentation / three amigos meetings etc. Links are version controlled so no expiration dates :)

    • Whimsical for flows, pretty much all macro level flows are managed in whimsical. Easy to handoff to dev and easy to maintain. (same as abstract static links)

    I'm looking to go to Zeroheight to have a more manageable Design system (easier to maintain complicated interaction) I highly advise you to take a shot at it.

    The big remaining issues for us are super complicated components and animations. Zeroheight makes it easier, but I don't understand how people do it, there is so many variable and static component/page layout does not remotely give enough info to a dev.. The only real way I'm seeing right now is stuff like framer where basically you just give them the code.

    Hope this helps.

    3 points
    • Marian Voicu, almost 5 years ago

      Hi Thomas,

      Thanks for the feedback, it does help me. Seems that we have a similar pain point. I know that what we need is an ideal tool that does not exist, but I needed to understand if other designers have this problem and how they resolved it.

      We have a similar process with yours, just that we use Invision Sync for versioning and Invision Inspect for specs, but still is not enough. I'm trying to make the switch to Abstract but it will take some time.

      Figma is not an option for the moment and when I had a look at the Zeroheight it looked that it will not be able to manage our DS. But I will have a better look.

      Thanks again

      0 points
  • Ankur Anand, almost 5 years ago

    I currently have this system ( though it does not use Confluence )

    I create one doc ( on Dropbox Paper ). The doc has everything needed to understand the designs. The doc contains following :

    • Link to files: Sketch, Principal, Framer
    • Link to copy doc : Our entire copy lives in GitHub ( Since we are a developer oriented company ). So I add the link to the copy doc that has messages, copy and reasons for them
    • If it has a complex flow - then adding an Overflow flowmap
    • A brief of customer persona, and understanding. I feel that anybody involved in a project should have a direct way to understand the research behind the designs. I also maintain important customer conversations in Airtable - So I add the link to the tags that can open relevant conversations
    • Explanation of the general concept
    • Adding various screens and leaving notes for them
    • Adding edge cases, defaults and blank states
    • I add link or embed relevant framer/principal prototypes where ever possible

    Once the document is done, I have a walkthrough call with the developers and the product team to walk them through entire thing.

    I am still looking for the perfect solution but haven't found any. Right now there are so many tools involved :(

    3 points
    • Marian Voicu, almost 5 years ago

      Thanks, This is a good flow and some good insights for me. For the moment I need for a better integration of the documentation / notes with stories and epics.

      0 points
  • Billy SweetmanBilly Sweetman, almost 5 years ago

    One thing I've done in the past is us tour points in Invision. I created a guided walk through with notes for all of the developer starting with image of how things generally broke down and then dove into the specifics on each screen. Now that we use Figma, we do everything right in the figma file. Which is nice because it's always up to date, which does have a Jira Integration.

    Hope this helps!

    2 points
    • Marian Voicu, almost 5 years ago

      Thanks, but in my case is not an option to switch to Figma for this project. An i think is not enough how you can document in it. But i will make a research on how Figma integrates with Jira.

      0 points
  • Account deleted almost 5 years ago

    Get in touch with developers. before jumping to any program/template/whatever, talk with the people who are actually going to develop it. They don't bite. In fact most of them are lovely people. Learn their needs, knowledge, technical capabilities and limitations. After studying their roadmap, refer here for the solutions and suggest the one's you've picked here. If they're okay with one, stick with it. If not, you have to build your own solution.

    Handovers are mostly similar (design and name your layers neatly and just use zeplin or avocode) but documentation is a completely different thing. It's created help readers problems. And every project has unique problems for it. You're a designer, do not just copy paste someone else's solution. As a designer, your main mindset should be focusing on how to solve problems. Talk first, learn, understand and then eventually you'll be solving the issue.

    1 point
    • Marian Voicu, almost 5 years ago

      Hi George, Thanks. This is what I am actually doing, talking, but not just with the developer. I'm talking also with the BA's, PM's and other Designers. And here on DN I'm trying to see how others tackled this problem. And sure, we will use the solution/s that works for the entire team, not just design.

      0 points
  • Kirsten Felbert, almost 5 years ago

    I have started making Design Readme documents, similar to whats described in this article - https://medium.com/livefront/documenting-design-workflows-6146495d1b52.

    The document has links to fonts used, where files can be found on out team google drive, InVision mockups, Zeplin & Overflow.

    We use Overflow.io for flows. you can get an online share link for these to put on Confluence or Jira.

    1 point
    • Marian Voicu, almost 5 years ago

      Thanks, but in our case Design Readme documents will not cover the need of documentation. But I will sleep on it and see if I can adapt or use in some way.

      0 points
  • Andrei Urse, almost 5 years ago

    This is an interesting topic, Marian. I am struggling with the same problem.

    1 point