Spec Handoff Workflow

IBM case study

How we redesigned our team's handoff process, built a custom spec solution, and scaled it within our organization.

The Problem

During my time at IBM, I had never been part of a team who really nailed the handoff workflow from design to development. Despite attempt after attempt to re-organize our team’s Box folder in new ways, the process of transferring production-ready spec files would always fail to remain organized and error-free.

The Project

In the fall of 2018, I finally got fed up; I decided to take a step back and see if there was a different way this problem could be solved. By the end of 2018, I had created a solution and deployed it to be used on my product team. In 2019–2020, I scaled this solution to four other product teams in the Watson Health organization.

in this case study, you’ll learn about:

↳ Old Process

↳ pain points

↳ User needs

↳ Tool Evaluation

↳ New Solution

↳ New Tools

↳ New Process

↳ Outcomes

The design team

Project Lead, Jane Depgen

Front-End Development, Luisa Neves

My role

– Evaluating old handoff process to identify pain points & user needs

– Exploring existing solutions

– Creating and documenting new process

– Designing UI for front end site

– Presenting solution to Watson Health-wide UX & Visual design guild

– Onboarding new product teams

What was our team’s old handoff process?

Step 1

Box Folders were created for different concepts, features, or pages of the product. Each designer may have their own working file, which includes all pages relevant to the particular page/feature.

Step 2

Whichever file includes a design that has been approved for development is used to package specs, generated by the Sketch Measure plugin. Sometimes these specs included outdated, irrelevant or WIP designs from the working file as well.

Step 3

The exported spec folder was saved into the same Box folder as the working files and the link was sent out to the development team via Slack/GitHub comment in the related issue. This was done ad hoc, for each design issue.

Step 4

Due to the structure of the exported specs, the Box link’s entire spec folder had to be downloaded locally in order for the user to view the interactive specs in a browser.

Step 5

By launching the html file within the downloaded folder, the user could then interact with the specs in their browser (Note: although viewing in a browser, this file is local, not a shareable link).

Step 6

Because the files must be downloaded, developers kept the downloaded files as their source of truth and would not receive updates when changes to the specs were synced to Box.

Why didn’t it work?

🔥 Lack of a controlled master file

Because there was no master file and no official review/approval process for the files being handed off, specs might accidentally include outdated, irrelevant, or unapproved designs.

🔥 No comprehensive release view

Because specs were exported from different working files for each issue being handed off, our team would have to refer to many specs to view a complete picture of an upcoming release.

🔥hosting/accessing the specs

Because specs needed to be downloaded locally to open, this prevented our team from being able to send/receive updates to the specs. This inevitably leads to confusion and unnecessary re-work.

What do our users need instead?

💡official review process

As a product team member, I need a clear distinction between work in progress concepts and production-ready work which has been prioritized, assigned to a release, and approved.

💡single source of truth

As a product team member, I need an organized, user-friendly, singular “source of truth” for all spec files which hosts a comprehensive view of each release.

💡improved documentation

As a product team member, I need more thorough documentation of when and what changes were made to the spec to ease the transition from design to code and improve asynchronous collaboration across teams and time zones.

Could any existing tools meet these needs?

InVision (Inspect mode)

The great thing about InVision is that everyone at IBM has access and there is Sketch integration via the Craft Plugin. The con? We were super disappointed by the inability to organize prototypes and create a folder structure.

THE VERDICT: ❌

Tools like Abstract, Zeplin, kactus

While new tools like these are exciting because they allow for better organization and team collaboration features (version control for design, finally!), the problem is cost. Unfortunately, our team is limited to using IBM-approved applications.

THE VERDICT: ❌

plugins like Sketch Measure

Amongst all of the problems with our team’s old workflow, this free Sketch plugin seemed to be working well! The only problem here is that the exported html files are exported locally and in desperate need of site to host them.

THE VERDICT: Can we leverage the html?

So, what did we come up with?

What tools are we using?

for master file management

In our new process, we decided to go beyond leveraging GitHub’s issue tracking features and also leverage it’s file management capabilities. To contribute to our master files, designers will submit a Pull Request which must be reviewed and approved before being added to our GitHub repository and spec site.

for Hosting the Spec Site

The biggest benefit of using GitHub for file management is that we can also leverage the free GitHub Pages site that comes with every GitHub repository to host our spec site! Because the specs generated by Sketch Measure are rendered through html, we’re able to easily publish the spec files to a shareable site.

for automating spec site builds

Travis CI provides us with automated spec site builds that are triggered by actions already in the user’s workflow. When a Pull Request is opened, Travis will post a link to a preview of the spec site where reviewers can explore the proposed changes without having to pull the branch and deploy the site locally.