28

How do you document the design environment?

over 4 years ago from , Full Stack Designer

By that, I mean the technical side of design. Not the decision making, research, and other background information that informs a design decision. In particular:

  • Do you have standard practices for documenting design kit usage, required plugins, minimum versioning?
  • Do you regularly update a changelog that details all the updates from one iteration to the next?
  • Do you ever use semantic versioning on your files or on your changelog?
  • Are there clear instructions for how to structure a design file? How to name artboards and layers? What is expected about grouping?

Developers have things like Docker to ensure consistent environments and linting tools that enforce best practices. Designers aren't likely to gain those tools but surely someone has designed a useful system that people actually follow.

So far, my searches have yielded little. I found this document on Notion which seems totally over the top. Deliveroo has something close to what I'm thinking but it's not quite there. TBH, I'd prefer that there weren't multiple tools involved, if possible.

I tried my hand at placing all the documentation into the prototype itself but it's faults make it difficult to continue. There are some nice perks, like making it a million times easier to find your project in Invision and changelog links directly to the affect screen. Beyond that though, design tools aren't really very good at text and it's super tedious to maintain.

annnnnddd, that's the end. Thanks y'all!

16 comments

  • Andrew CiobanasiuAndrew Ciobanasiu, over 4 years ago

    I had a similar post a few months back.

    Definitely some helpful suggestions there. I did a lot of research and analysis of options for us.

    Ultimately I decided to create a repo in our company Gitlab instance and maintain a wiki there. Easy to manage, developers are comfortable with it already, didn't require another tool or account, free, and while not the sexiest new thing, it works for our crew. Here, I have things like recommended plugins, artboard layout and structure (with examples), naming conventions for layers, export and slicing best practices, and so on.

    As for versioning, we use Sketch and Abstract. Abstract has been truly wonderful to use, even with only one designer. I am still working out the details of applying semantic versioning to design files. I found Nathan Curtis' Medium post on the topic to be particularly useful. He dives into a few things you are mentioning regarding versioning.

    Edit: Doh. You literally suggested some of the products in the thread I posted earlier. I'm blaming this on Friday brain.

    6 points
    • Jason Spidle, over 4 years ago

      No worries, that was definitely a useful post with some overlap. That Nathan Curtis post seems super useful and I definitely have been eyeing Abstract. The more people encourage it, the easier it might be to convince everyone else. I just wonder how easy or effective it will be trying to convince other designers on my team to make commits and pushes, etc.

      1 point
  • Yasen DimovYasen Dimov, over 4 years ago

    Hm, I really have no time to write everything up, but this is such an interesting topic, so I'll throw:

    GitHub via Kactus + Sketch and MD files...

    If it's interesting to anyone, I can expand at the end of the day.

    EDIT: Obligatory, I don't use InVision anymore and I don't intend to ever.

    5 points
  • Artur Eldib, over 4 years ago

    Figma + Notion

    4 points
  • Nelson TarucNelson Taruc, over 4 years ago

    Unfortunately, no best practices I can point to/that we use. Here's how we do it.

    Documentation: The design system IS the prototype, with navigation and everything. No external tools like a design system manager. Just a link to the prototype. (Figma is awesome for making this so simple, but you have to commit to designing in Figma to make this work … you could probably make this work with Sketch if you save your prototype to the cloud).

    Changelog: Slack channel

    Versioning:Yes in both files and changelog, but it's very high level (Mk 1, 2, 3, 4) we don't do point versions.

    Naming: We haven't figured this out yet either. Generally we defer to what our developers prefer (which is often camel case).

    FWIW, I've researched other DLS implementations and it's really company-specific. What works at one org would be a disaster at another. I think that's why it's hard to find a common set of best practices.

    4 points
    • Jason Spidle, over 4 years ago

      Thanks for sharing. Definitely understand that without a killer tool that nails this problem, it'll vary a lot from team to team. Do you match developer preferences on files to expedite dev?

      0 points
  • Sylvain MarettoSylvain Maretto, over 4 years ago

    Also, this article of Deliveroo is more about looking for some legitimacy for the design team than real knowledge. I know how it works there and at Foodora, same that everywhere else. You have to use the softwares the company has licences payed for, but it's not as defined/structured/rigid as they say.

    This is the employee handbook of the agency one story below us in Berlin, and I don't really see what one should go further design-wise https://diesdas.digital/wiki/about-this-wiki

    it's (almost) perfect as it is.

    1 point
    • Jason Spidle, over 4 years ago

      This wiki is excellent! Thanks for pointing it out to me.

      And yeah, the Deliveroo article isn't really covering the same topic. It was more trying to show that I did do some research and this is about as close as I found...

      0 points
  • Sylvain MarettoSylvain Maretto, over 4 years ago

    I think those behaviors evolve too fast to be written somewhere as a book of law. It is more of an ongoing discussion during design reviews, weeklys etc.

    1 point
    • Jason Spidle, over 4 years ago

      Definitely a good point. I guess I wasn't super clear about my primary goal in my post. The biggest issue I've been running into is that our design team has went from just myself to me + two other designers that I manage. When switching between projects, we're all having difficulty knowing which plugins were used, if there is some kind of standardization in file naming and grouping practices, if there is a grid and when is it okay to deviate, etc.

      0 points
  • Jason Spidle, over 4 years ago

    Tacking onto this, one thing we've just started to do is use Wake throughout the day to share in progress design. The thinking is that by sharing design, everyone on the team will be more grounded in how the design is evolving and if they end up needing to work on that project, they'll come in with some knowledge. Before, each person on our team was kind of in a silo, unfortunately.

    In any case, anyone else have experience with Wake? It seems dormant so I worry that it isn't a long term solution. Are there better tools for design teams to easily share in progress design directly from Sketch. That workflow is crucial to adoption...

    0 points
  • Perttu Talasniemi, over 4 years ago

    I'll keep it short: Cool project bro!

    -4 points