What is effective documentation for design – dev handover?

Text documents for requirements have long gone from most companies, but identifying the ideal level of detail, format and location for the source of truth depends on many factors varies from company to company and team to team.

At worst, the latest mockup sits in a designer’s set of files in various chunks, making handover patchy and hugely dependent on one person’s availability.

  • Digital whiteboards are fab, but can become unwieldy when hi-fidelity specification is required.
  • Physical printouts and notes on walls are a great discussion tool, but not for remote or hybrid working.
  • User journeys lack the UI so are too vague for development or require matching up additional items.
  • Interactive prototypes require you know where to click, and by that point you might have well just created it in code anyway.

I think I’ve seen and tried every combination possible. I have shied away from documentation on account of it sounding waterfall and not lean enough. After all, there is no document in the world that has enough detail to be complete “enough” and that makes it too big an investment of time. The product needs the investment, not the documentation, so what approach works?

Mostly the choice has been organic based on the people involved and the software they use. The latest trends as well as the skills of the team are also huge influences. But if you want to be strategic about documentation, imho there are a couple of important factors that should inform your choice.

Product maturity

If the product doesn’t exist yet, napkins and notes are good enough. The product is small and it’s clear what it does. The coders are commenting and vision documents from stakeholders combine into the start up documentation set. A great front ender will mock up an idea in code quicker than on paper or design software, facilitating discussion and testing.

As the product stabilises, capturing some reference to design and business decisions and pivots is more useful than it may seem at the time, especially for a company that is starting to grow.
There is also a risk in having this knowledge in one person’s head. People move on then you’ve got an issue.
If you have remote workers, a wiki page of some sort can be useful for quick comments and screenshots. But don’t get lost in difficult to use wiki formats and protocols; it’s better people can jot down their comments when they make an update. This makes the decisions more visible. Whether they were the right ones is a different topic. Jira boards are considered documentation enough by some, but can be impenetrable to non-dev folk. Consider the team, location, skills and needs.

If the product is mature and has people (both users and workers) needing to consult what it does now to know if it’s working correctly, you need some kind of reliable documentation. Ideally Jira tickets, knowledge base and forum, as well as the product update page and website all tell the same story.
However, employees and stakeholders need to know one place to look for the different types of artefact (design mock ups, product decisions or the reasons why it’s so great). Notes and napkins at this point are a nightmare because they are not collaborative enough. However, if you have a channel, blog, wiki or wall, you can use that same napkin, just remember to photo and comment it.

If a legacy redesign is underway, capturing what used to happen and what’s changed is important, but communicating it across the company and user base is more so.

Team skills and size

Who is hands on in your product design team makes a difference. If everyone codes, clearly you won’t have the need for more design mockups, commenting and screenshots for customer support may work well enough.

If the team is more mixed, the need for a common accessible product design snapshot is more important.

Mockup map

A map is quicker to put together than a fully interactive prototype, and it’s definitely a clearer discussion tool. Whether you consider yourself to be a visual thinker (I do), or whether you believe all that to be nonsense, for me looking at the same picture is priceless. “I’m glad we all agree” from Jeff Patton captures this beautifully.

This applies to when we’re ready to share with the wider team, but it actually really helps the designers spot gaps and obstacles, and us all to rethink different aspects when we can look at the same thing together.

Ensure the happy path is communicated, variants are then easily understood.

Note I didn’t say it was quick to create a map, it’s just quicker than a fully interactive prototype. It still needs the thinking and iterations. Depending on what stage the design is at, they can be sticky notes and rough sketches, cobbled together with borrowed screenshots and videos. It will resemble a vision board more than a UI design in the early stage and a hi-fidelity flow with final art boards in the latter.
This process and output will outline the user journey and add in questions about tech feasibility in one place.

The important part is to make very clear which is the basic flow, the one that provides the outcome for the user and the organisation. Without that, additional editing and nice to have options can overshadow the core flow and the main point gets lost or diluted down.

If you can get to a map that’s clear and well-defined, an interactive prototype or the product itself is then quicker to build because you have all the pieces and most of the questions answered.

Software choices

Figma has been a game-changer for us, but not in the way I had anticipated when I subscribed our budding product design team.
I had used it before for simple wires and interactive mockups, and expected it to be mainly useful for testing, but where it has really come into its own has been with the relatively new Figjam boards, which we use to map out the flows.

Happily, there are many software alternatives out there and new ones emerging. Whichever tool you find, a giant digital canvas is great for remote collaboration. What I didn’t expect was it to fill this gap so well in terms of lean documentation.

Miro has always been a pleasure to use, but our mockups are in Figma, so Figjam means one product covers our needs. Zeplin is also appreciated by developers for picking up designs. It has recently opened up Flows, but we have not found them as useful yet as our Figma and Figjam combo.

Your story

What software or practice has revolutionised your lean handover practices?


Leave a Comment

Your email address will not be published. Required fields are marked *