I was sick of opening up the publication panel and seeing components that had no business being in there. Who edited these? They look exactly the same! Did someone (me?) update the description and forget to hit publish? How long ago since we last published these components anyway, and what were those edits?
I can't answer any of those questions with Figma's current analytics tools. But I can build Coda docs...
Coda doc architect.
1 month
Our team of designers frequently expressed interest in things that detach data couldn't help with. I would hear statements like,
"I want to understand what changes were made to a component before I go editing and re-publishing it." That's understandable, having context can give you confidence you're publishing a productive edit. This seems especially critical for new joiners!
"I don't accept updates when they come through, and while I feel kind of bad about it, I don't have the time to investigate what the change was." And it shouldn't have to feel like an investigation! Hitting "accept" on an update should feel easy and desirable (not laden with anxiety and effort).
"I want to contribute more to the design system." Great, I want that too! So we will need a way to measure contributions.
I needed some sort of process and analytics system that let me:
The data I need to track those kinds of things is not complicated. It's just three things:
In an ideal world I'd able to extract the first two lists directly from Figma, but alas, it's not possible (not that I know of). In the mean time I use my other favorite tool to do this: Coda.
To make the first list (the list of published components) I had to put in a couple hours of up-front work copy pasting information from Figma into Coda. I grabbed components' names and node links, and stored them in a table:
After populating that table, maintaining the content was easy. New components get added and existing ones get deleted by making publications! So the next step was to create an experience in the same Coda doc that me and my designers would use to craft excellent publication notes. The workflow goes like this:
After you've made your edits in Figma, you go to the Coda doc and select the library you're publishing from:
Then, just like in Figma's publication panel, you need to select all the elements that you're including in the publication. if the publication you're making includes newly added elements, there are buttons that let you create new data table rows for new components, variable collections, or groups of styles.
After you've made your selection of elements, you need to categorize it as a Defect Fix, Small Enhancement, Large Enhancement, or New Material. To make this as straightforward as possible, I listed out all possible edits that could be made in Figma and categorized them against those contribution types:
After you've made your selection of edits, you get to craft your publication note. Depending on the type of contribution, we can offer suggestions for what will make that note useful to consumers. And because we're doing this in Coda, all our table data is @-mentionable! We can @-mention people, other publications, components, variables, styles. This deep-linking enriches the history of the file that gets built with each publication.
This workflow actually changed my publication habits for the better. I found myself making more frequent, but more granular publications (one or two components at a time). This helped me get more specific in my notes, and allowed consumers to have more control over what updates they accepted VS held off on.
Once you hit that "copy publication notes" button, a formatted message is added to your clipboard to paste into the Figma publication note panel. On the consumer end, a library update looks like this:
The publication type (eg Large Enhancement) helps consumers understand the scope of the change before they dig into diff-checking. The ID number gives them a way to reference that exact publication in a Slack message or Figma comment. And most importantly, we call out whether or not they can expect breaking changes. That part was crucial. Breaking changes are why designers hesitate to accept changes to begin with!
Remember, this doc isn't just about making accepting publications easier.
One of the other goals was to track contribution stats. I wanted to be able to answer questions like,
Well, my Coda doc isn't just capturing which components are associated with a publication. It's also logging:
Knowing "who" and "when" in addition to "what" (which library, and components) and "why" (good publication notes) allow me to build out a reporting dashboard that shows a super rich history of all our libraries. Cue dashboard montage:
<div class="horizontal-rule"></div>
We didn't have this Coda doc at the time our, so the history is incomplete. But it does its job. If me or anyone on my team asks those questions from earlier, I can confidently answer them with high precision.
When it comes to component-level documentation, this doc gives us a massive advantage: we can place a component's change-log—a list of every publication its been through—right beside all the usage documentation. Here's an example of what our design documentation looks like for our <span class="figma-component">❖ Alert</span> component:
Every component documentation view follows this structure:
We can also reference specific publications in the design documentation copy to explain how and when certain design decisions are baked into components.
