Juha-Matti Santala
Community Builder. Dreamer. Adventurer.

Potluck #3: My workflow

This is the final part in a three part blog series exploring my most recent tabletop design project, Potluck. Previously, Research and Design explored the origins and design considerations of the project and The Deck looked at the form and function of the deck.

This part is for all of those who are interested in building similar projects themselves. I used technology and tools familiar for software developers to turn design and data into generating the project and keeping track of the project.

Basic workflow

When I created the previous project, Project 108, I built everything manually in a graphic designer. This meant that if I ever needed to make changes to layout, I needed to make it 108 times. Never again.

For this project, I wanted two things to happen: I wanted a way to manage the content of the cards in a convenient way and I wanted to be able to generate the full deck with a click of a button.

Data: CSV & Spreadsheets

I wanted to manage the data in spreadsheets because they map nicely to cards: row equals one card and column equals one element on a card. Also, the capabilities of spreadsheets make managing data easy: I could use formulas and autocomplete features to make it easier to manage the entire data set.

For text, I wrote the text into the cells and for images, I wrote the file's basename into the cells. I then stored the images in an assets folder in my project.

One big benefit of spreadsheets is that it maps nicely with CSV files and that's great because CSV files can be read by other software and also, they are a fully text-based format which makes it easy to track them in version control.

Here's a simplified example:

number suit role top-right-color
1 hearts Guard red
2 hearts Priest blue
3 hearts Bishop green
4 hearts Handmaid yellow
5 hearts Prince orange

To add a new element, I'd create a new column, give it a name and then fill in the data. For me, an "element" usually refered to a "slot in the card layout" but ended up sometimes having 2-3 columns per layout spot since sometimes I needed to change the layout a tiny bit for some items depending on other items.

Using spreadsheets fulfilled my first need: a way to manage the contents in a nice way.

Layout: XML and Multideck

Sometime in 2022, I learned about Multideck. It's a macOS software built for exactly this use case: combining CSV and layout files to generate cards.

One thing I really really really like about it is that it uses GUI to create the layouts and then stores them in XML files. XML files are text so they too can be nicely tracked with version control.

Multideck is an okay software. It does what it promises and can solve many problems. But as someone who is used to programming and tinkers in graphic design software daily, I keep dreaming of features from those two workflows. I wish there were more support for conditionals (I solved this by creating more columns in spreadsheets and using formulas there) and more tools to help with pixel-perfect layout (like rulers and snapping to those).

At one point my CSV file grew too large and Multideck kept crashing on startup so it doesn't support very long lines in CSV files. It's not the end of the world though because you can minimize the CSV quite a lot if needed with smart design and tooling.

Version Control: git and GitHub

I've mentioned twice above how happy I am of the text-based formats with CSV and XML. The reason for that is that it enables me to do iterative development with software development practices. I use git as my version control tool in this project.

Quick primer into git for non-developers

Git, or other version control software, works by saving steps in the process by comparing the changes – called "diffs". If you've ever worked on a Word project and have multiple versions named "Thesis_final.doc", "Thesis_final_2.doc", "Thesis_final_final.doc" and so on, you're familiar with the problem.

Git stores these changes in commits and each commit is a set of changes in text. If I add a new column into my CSV file, I can store that change as a commit. If I change something in the layout, I can commit that change in XML as a commit.

The beauty of version control is that I can jump back in time whenever I want into any other commit. So if on day 2, I experiment with something, then later decide to remove it and even more down the line, want to bring it back, I don't have to remember how it was done. I can look into the version history.

It also enables working in "branches" which means I can keep my main project intact and make experimental changes in a separate version without having to worry about making a mess.

Pull requests for features... kinda

In the beginning, I tried to work in a way where one pull request (a set of changes, can be multiple commits) would map to one feature in the deck. I wanted to have a history where I could see clear steps of each new feature or change.

To be honest, at some point, I got bit lazy with that as I got more excited about experimenting with new features. But the commit history is there and it's mostly feature-by-feature.

I kept the project in GitHub and kept updating the readme when new major changes happened. I did it so I had a reason to export individual items after each step so I would have a nice history of development of the project.

The big picture

With these three main tools, I had a superpower in my hands: at a click of a button, I could generate a full deck that could be printed for testing or sent to a printing house for production. It made me more excited to experiment and to try out new things without having to worry about having to do everything 106 times over.

I think this was also a major reason for why this project is so much better than the previous one. I did kind of get "burnt out" by the previous one because every change required so much effort that I didn't want to add new things or make changes. Now, every change was easy to apply to all cards, easy to revert and because of the version control, I knew the good experiments would be saved and bad experiments wouldn't cause issues.

Syntax Error

Sign up for Syntax Error, a monthly newsletter that helps developers turn a stressful debugging situation into a joyful exploration.