The handoff doc

I used to hand designs to engineers with a link and a hopeful message. Now I hand over one page of text beside the link, and the questions I get afterwards have dropped by about half. Dmitri, who builds most of what I design, says he reads the page first and the file second.

The page has five headings:

• What this is for, in two sentences
• What is decided, and what is still open
• Behaviour that the design does not show, such as loading, empty and error states
• Anything I would cut if time runs short
• Who to ask, and when I am out

The “would cut” section was Dmitri’s idea. I resisted it because it felt like giving permission to ship less. It turned out to be the most used part. In November, a feature was two days late, and the engineers cut exactly the two things I had listed instead of guessing.

Where it lives

In the same folder as the design file, named handoff.txt. I tried a shared document and found nobody could tell which version was current. A file in the folder, edited in place, is current by definition.

I review the page with the engineers in the same session as the design review, so the open questions get owners on the same afternoon. The weekly update then links to the page instead of repeating it.