Three months earlier…
Prior to making the proposal — and ultimate commitment — for Abstract, I had been researching several version control options as part of a larger rollout of the upcoming O’Reilly Design System. I became really intrigued about the power of using Sketch with Git/GitHub after reading this post from Andree Huk of blended.io. So much so in fact that I had set up a design-library repo, was testing Sketch commits via Terminal, and was beginning to write documentation for how the design team should begin using this as the de-facto standard for sharing our design files.
But… as much as I was loving the idea of being ahead of the curve by using GitHub, I was still very hesitant that the rest of the team would be willing to adopt this new workflow, despite interest & excitement from the team while sharing progress during discovery. And then Abstract popped up on the radar… again. I had come across it during my earlier research but dismissed it due to the fact of needing to introduce yet another service into the mix. All product squads were using GitHub, but the notion of it not gaining traction with the design team was enough to send me down the road of evaluating a 30-day free trial.
Fast forward to today
The design team is fully set up and beginning to integrate Abstract into their daily workflow which is really exciting to see. The rollout hasn’t been without questions though. The overall concept of Abstract can get lost on anyone that’s not familiar with how Git/GitHub works. Even with some familiarity or exposure to GitHub, asking a designer to start working more like a developer can present some challenges.
Fortunately, Abstract does a very good job of explaining how it works. Taking a page from Kevin Cheng’s comic strip approach certainly helps, but they also offer a strong on-boarding deck and a support knowledge base that answers most immediate questions. Even with all of this great documentation, there were still a few things that didn’t soak in all the way. To help the transition go more smoothly, we set up a dedicated Slack channel in-house to post updates and field concerns. Here are some of the most commonly asked questions and how we have addressed them so far.
Any tips on how to use branches cleanly and efficiently?
It’s important to note that Master is also considered a branch, so let’s start there. First, the naming of ‘Master’ can cause some confusion. Being singular could make one assume this would be one file. Pile on messaging like “single source of truth” and “one final version” and it really makes you think that Master equals a single file, but that’s not the case. Abstract clarifies this on their site, but it gets overlooked; “Each project has a Master and can consist of one or several Sketch files.” Knowing this opens up a world of possibilities when it comes to how you manage your projects and branches.
Split your Master
Depending on the type of project you’re working on, you could split your Master into sections or pages of an application, or groups of work assigned to an individual. Doing this would allow someone to create a branch and only make updates to an individual file without blocking others from making updates to other files within Master. This is an easy way to avoid merge conflicts and creates efficiencies in a congruent team workflow.
Version with [nested] branches
As you’re working on a new release, create a single branch for the new version and fork subsequent child branches from there. This removes the dependency on frequent updates to Master and allows your team to maintain the same congruent workflow, except now you’re merging to the parent branch until the final release is ready to be merged into Master.
Create new art-boards
Another good tip when making updates in a team environment is to duplicate (and rename) art-boards when riffing on someone else’s work, or just create a new art-board entirely. This will help avoid merge conflicts when branches sit in review for a while before getting merged.
Alden Spence published some additional tips while I was drafting this post. Check it out on the Abstract blog.
How should we name our branches?
At O’Reilly, we’re always striving to have our designs match the coded environment as much as possible (and vice versa). This requires a close relationship to the developers responsible for implementing the designs. Anything that helps facilitate that conversation is a win. So it only made sense for us to adopt the same naming conventions that our Dev’s were already using on GitHub.
For our front-end teams, that looks something like this:
<type>/<ticket-number>/<title> or component/taco-1018/sidebar-nav
- We replace <type> with names like: page, screen, feature, component, etc.
- <ticket-number> gets replaced with the JIRA ticket number if the issue has been assigned. If not, we’ll replace this with the working project name.
- <title> is a one or two word descriptor of the main item being worked on for easier reference
Of course this is only one way to do it. Share your feedback in the comments below to tell us which naming conventions work for you.
Are there any file size limits we should be aware of?
A good best practice is to keep your Sketch files under 100mb. Having bloated files can decrease productivity in Abstract due to the fact that it runs a Diff every time you commit a file. This means it’s processing the entire file to see if there were any changes since your last commit. The larger your file, the longer this will take. This is why it’s better to split your Master and Libraries into fewer, smaller sized files.
What review & approval workflow should we establish?
GitHub has amazing permission controls when you create a new branch. You can lock down who can make commits, and more importantly, you can set up multiple levels of required reviews before anything gets merged. Abstract does not currently offer much around controlling the review cycle (but I know for a fact this is something they are working on.) Until those features get released, it’s best to set up a manual process that your entire team is willing to follow.
For us, that’s fairly simple right now:
- At an org level, connect the Slack integration to a dedicated channel. This keeps the team in the loop on the latest commits across all public projects and gets more eyes on work being done overall.
- Use labels within Abstract to mark when a branch is ‘open for feedback’.
- Create an @ mention to at least one other designer on your squad to conduct a peer review.
- Create an @ mention to a Design System team member if you have doubts about your interpretation of the guidelines or items from the library.
- Ping your squad ahead of merging anything into Master to ensure everyone is on the same page.
O’Reilly’s hiring
We’re always looking for smart product designers and front-end developers to help build the future of our online learning platform. Send me a tweet or DM me touhey if you’re interested in joining our growing team.
