Available for your project. Reach out today!

Documenting Design

Crossing the handoff chasm between design and engineering.

Note: This was originally published on Medium. Reposting on here for archival purposes.

When I am working on a design, eventually I need to hand it off to teammates to code up. By now everyone has hopefully participated in some part of the process, is familiar with the design, and—fingers crossed—shares the vision of what we’re creating. But how will my engineering teammates build out this wonderful thing?

It’s very possible to have a crack front-end engineer (I do) and back-end guys capable of writing solid front-end code (they’re getting there), but often this isn’t the case. When this happens it’s up to me to provide something which meets their needs and enables them to build what I’ve designed.

Enter The Design Implementation Guideline!

A Design Implementation Guideline (DIG) is intended primarily for engineers to use as they build an interactive experience. It is a tool for having a more productive conversation with my engineering team and is considered by us to be a living document that is added to as we identify additional implementation needs.

My approach originated from a request from one of the talented Front-End Developers (FED) on my team, Daniel Sellers. He said, “Make Style Tiles.” So I started researching them—I had heard of them previously— discovering as I looked at my design and asked myself the question, “If I was building this, what questions would I be asking?” that Style Tiles fell woefully short of what my engineering team needed.

That’s not to say Style Tiles don’t have their place in the process. They’re great when you’re trying to establish the visual personality of a product and are presenting it to stakeholders, but as a practical tool for implementing a design, it’s mostly fluff.

To provide something useful, I began with what I knew they needed: colors and fonts. Then came the header and then some general specifications about layout, miscellaneous UI elements (buttons, alerts, icons) and patterns, etc. Over time this document has grown. And as a result it has provided great value to us as a team in the following ways:

  1. Design, documented. This is not a touchy-feely artifact. It’s what I designed, but deconstructed into its component parts with measurements, rules and notations. By deconstructing and then rebuilding the design in a modular, disciplined manner that my engineers can implement it ensures I can stand by each design decision made along the way. It deepens my own understanding in a way only a maker understands.
  2. The QA team has a quantifiable tool to measure the implementation of the visual design. Prior to this, QA-ing a UI was purely subjective as all they had to go by in evaluating the visual design was a PDF or JPG comp and maybe a lifeless HTML/CSS prototype. Now they have a solid reference with clear measures for implementation success.
  3. It serves as a training tool for developers aspiring to learn front-end development by exposing them to the language and rules used by designers in an approachable, easy-to-digest format they can understand.
  4. Most importantly, the DIG explicitly shows engineers the structure behind the design and how the component parts come together to form a complete experience when accompanied by the visual design comps (which I always share and discuss with them as I’m creating the design in order to avoid any technical roadblocks.)

While I know this approach won’t work for everyone, it has for us on our last few projects. It does take a considerable chunk of my time up front to create, but as the implementation progresses with me—the designer—removed as a bottleneck for them and a ready reference in front of them, we are both freed to focus on what we respectively do best and the end result is much better.

By using DIG files—paired with consistent design reviews—my team has been able to implement more complex and robust solutions than other teams around us. And they’ve done it faster and better (on time and under budget) because they’ve not had to wait for answers from me and their focus has been on the technical aspects rather than wondering what the font size of the h2 is. To me that fits within the definition of implementation success.


Read some more...