Fabian Krumbholz

How I build a hands-on workshop that people finish

· 17 min read

In short

A hands-on workshop is easy to announce and hard to run well. You have two hours, a room full of laptops with different systems, and a Wi-Fi you’ve never tested. Whether people leave with something that works is mostly decided before the workshop starts.

This article is the prep guide I wish I’d had for my first workshop. It’s for GDEs, and for anyone else who wants to build and run a technical workshop: what to prepare, what to test, and what to have ready for the moment things go wrong. Most of it I learned from mistakes, some of them made in front of a full room.

My examples come from my most recent workshop, at DevFest Milano on 10 October. People came in with a laptop and left two hours later with their own portfolio site, live on the web, built by directing AI agents in Antigravity. The guide and the slides are public. Take whatever is useful to you.

What makes a workshop a success?

For me it’s one thing: people go home with something that has value to them. It won’t be finished in two hours. But they’ve seen how to start, they’ve done it themselves, and they leave thinking “I can do this, and I can continue at home.”

So I don’t see a workshop as something complete. It’s the start of a journey, or at least the chance to try one. Afterwards, each person decides whether to keep going.

Many people want to build something and keep putting it off, because they don’t know where to start. A workshop takes that away. When you’ve built a working site in two hours, the next question comes on its own: what could I build in two days? That’s the question I want people to take home, because it’s what makes them continue.

Three things follow from that.

Teach the system, not every detail. In two hours nothing gets production-ready, and it doesn’t have to. People should understand the basic steps and how the parts fit together, and then start building. This is my own biggest problem: I always want to put too much in. Simplify more than feels right. The details can come later, once people enjoy it enough to want them.

Name the shortcuts you took. Say openly where you cut corners, so people know where they still have to go deeper. My guide has a page called Do it professionally, and the Behind-the-scenes pages put each shortcut next to what a real project does instead.

Give them a way to continue. A Next steps page shows how to add their own content, keep editing and publish again. Three Behind the scenes pages explain how the agent system is built, and how to build the same kind of system for your own use cases.

What do people get from you?

Three things, and I tell them at the very start.

A slide deck for the theory. I share it with everyone. Otherwise people write along or take photos of the screen, and while they’re busy taking photos, they’re not listening.

A guide. The guide leads them through the workshop step by step, and it stays online afterwards. That matters as much as the guide itself: people should still have everything when they continue at home.

A repo to start from. Nobody starts with an empty folder. The template repo has everything the workshop needs: the install scripts, an AGENTS.md with the rules for the agents, and the files for each block, already prepared. The setup script turns it into each participant’s own repo, so their work stays with them after the workshop.

So in the first minutes I say it out loud: you get the slides, a guide and your own repo, and all of it stays online. If you don’t say it, people will ask, and some of them will spend the theory part photographing slides.

What should the room spend its time on?

On the fun parts, the tasks people learn from. Everything that is boring, teaches little, or isn’t needed to understand the big picture of a step, I automate or prepare: installing tools, setting up the repo, demo content to start from. In Milano, every participant’s repo started with a complete sample site for “Ada Example”, a made-up person. Nobody had to build a site from an empty folder before they could start on the interesting part.

People should still go through every step once. But the steps where they would learn little, I prepare for them, and the guide explains how to build those parts themselves if they ever need to, in the Behind-the-scenes pages.

The short time is also why I remove every risk I can, and tools are the biggest one. Every tool is one more thing to install, one more login and one more thing that can go wrong in the room. So I use as few tools as possible, and tools people already know. In Milano, participants needed two accounts: a Google account, to sign in to Google tools like Antigravity and Stitch and for the AI model quota, and a GitHub account, which most developers already have. Nothing else.

This matters beyond saving time. The goal of the workshop is that people want to continue afterwards. If the two hours feel like a list of boring chores, nobody has any motivation left at the end. So the tasks in the room have to make sense, and they should be fun.

Why does the setup get the most preparation?

The setup is the one block without a shortcut. For every other block there’s a way to catch up with the room. The setup, everyone has to finish, or they can’t continue. It also comes first. If it’s slow, frustrating or broken, the mood is set, and the workshop is more or less over before it has started.

I learned this the hard way. In an earlier workshop the setup took ten minutes for some people and an hour for others. I had to move on with the room and had no time left for the people still installing, which was frustrating for them and for me. In another one I had written the terminal commands for a Mac, and in the room almost everyone had Windows.

So the setup gets more time and testing than anything else.

Install as little as possible. The less people have to install, the less can go wrong.

Automate the rest. Nobody types or copies commands into the terminal ten times: it bores everyone, and one typo or one skipped command leaves the person stuck. Instead there’s one setup script per system, install.sh for macOS and Linux and install.ps1 for Windows. In the guide, the command sits under one tab per system, so everyone gets exactly the line they need. The script installs what’s missing, creates the participant’s repo and opens it in the IDE. At the end it prints a checklist: “[ok]”, or “[to do]” with the one thing the person has to do. Expect unusual setups too, like a work laptop where people can’t install much. A script that says exactly what’s missing helps there more than ten manual steps.

Start before the start. Ideally people install everything at home, and there’s a prep page for that. But at a DevFest people often walk in without registering. So when I enter the room, the projector already shows the first three steps: download, install, connect to the Wi-Fi. Early arrivals are mostly done when we start. And for the person who always arrives ten minutes late, every slide has a footer with the Wi-Fi password and the link to the guide, so they find their way in without disturbing the room.

How do you test the setup?

Run it yourself, from nothing. Before every workshop I delete what I had installed and go through the whole workshop the way participants will. I only have a Mac, so the other systems get tested by machines: GitHub Actions runs the setup scripts on fresh Mac, Windows and Linux machines with every change. If a colleague or a friend has another system, test at least the critical steps on it. My own mistakes during the run-through become warnings in the guide, at exactly that step, because participants make the same ones. And in the room I know every step well enough to see at once where someone is stuck.

Time every step. My feeling for how long a step takes is often wrong, in both directions. The measured times are what the time box for each block is built on, plus some extra: in the room, people are more distracted than I am at my desk.

How much theory?

At most a fifth of the time. Otherwise it’s a talk, not a workshop.

Most organisers I’ve worked with give a workshop two hours at most, and two hours go by very fast. About 20 minutes go to the introduction and another 10 to the setup. That leaves about 90 minutes for building.

I always start with the result: what you take home today, and what you’ll learn. Then that they get the slides and a guide that stays online. Then why we do it, then how, and then everyone starts.

How do you write a guide people actually follow?

I copied the format from Google Codelabs: a guide you click through in the browser. Then I changed four things.

One step per screen. My first version showed a whole block, with several tasks one below the other. People read it, missed a paragraph, skipped a step that mattered, and got stuck two steps later. Now each screen has one step, and people click Next to see the following one. Nobody skips a step by accident.

Short text. Most mistakes in my workshops happen because people don’t follow the guide, and they don’t follow it because they didn’t read it. They skim, read half, and do half. So each step says what to do and nothing more.

A check at the end of each block. Because people skim, I don’t trust that every step was done. So each block ends with a short “Done when” list: these things must be true now. Even better is a script that tests the result and reports which step is missing. Whether that’s possible depends on the workshop and the topic. Where it is, it’s the best solution, and in my workshop the agent runs that check for people (more on that below).

The reason goes in a box for later. This is what I miss in Codelabs. They’re fast: copy, paste, next, copy, paste, next. After two hours people don’t really know what they did, and many leave thinking “that was complicated, I don’t want to touch this again.” That’s the opposite of what a workshop is for. So every step in my guide has a dashed box, “Why we do it this way · read later”. People skip it in the room and read it at home, when there’s time to understand.

Can the workshop run without you?

More or less, and that’s what I build towards. My workshop was about building with AI agents, so the agent could also help with the workshop itself. The template repo has an AGENTS.md with the rules for the whole workshop, and one skill per block. When a participant starts a block, its skill leads them through it: it asks the questions it needs, one at a time, and says when the block is done. If someone is stuck, they ask the agent, and it knows the workshop well enough to help.

There is also a status check: a script that looks at which files should exist by now and which are missing. When someone asks me for help, I tell them to open a fresh chat and type “Where am I?”. The agent runs the check, finds the step that was skipped and says what to do next. That helps me too, because I see at once where the person is.

Train the agent for the moments when things don’t go as planned: finding out where someone is, which steps they skipped, what they need to do next. That’s exactly what people who arrive late or fall behind need.

This worked very well. I had a lot of free time during the workshop, enough to talk with people for a few minutes each. That’s the part of a workshop I like most, and usually the part there’s no time for.

I try to spread that time evenly, not only on the few people who ask the most. Everyone should get the chance to ask something. And I ask too: what they do, where they come from, what they’ve built before. I learn a lot from that, especially which parts I didn’t explain well enough.

Sometimes the best help isn’t me. When someone is stuck on Windows and I know that another participant with Windows already got past that step, I bring them together: “Can you help? How did you solve it when you were at this point?” That works very well.

How do you keep everyone together?

This is the rule I care about most: the whole room moves to the next block together.

If some people keep working on the old block, others are two lessons ahead, and everyone in the room is at a different point. When I walk around to help, I first have to find out where each person is. Worse, people who fall behind often never get back to where the room is. They leave without a finished site, and they get little out of the workshop.

Two things keep the room together:

How do you end the workshop?

If there’s time left, because the room was faster than expected, I show what people built. In the guide, participants can share the address of their finished site, and it appears in the slides automatically. Then I put the sites on the projector, one after the other.

Everyone sees what the others made, and every site looks a little different. That gives the room the feeling: we really got a lot done today. People go home proud, and with the thought: I made something this good in a short time, I want to learn more about it. That’s exactly the feeling I want them to leave with.

What happens after the workshop?

Feedback is part of the workshop, not an extra. My guide has a Feedback step before the end, and everyone goes through it. It tells me whether people reached the goal of the workshop, how they liked it, and above all what they would do differently.

I take that seriously, and I act on it right away. After every workshop I change what I learned before I forget it. That’s how the workshop gets better over time. Two examples from the last rounds:

A workshop will never be perfect. Something will go wrong. The better you prepare, the more likely it’s one problem you can solve on the spot, and not twenty at once.

One thing I haven’t solved yet: what happens weeks later. My idea was a Discord community for everyone who took part in one of my workshops, a place to ask questions, share results and get feedback from others. That would help people keep going, and if they don’t keep going, much of the workshop was for nothing. But I have a full-time job, I do workshops on the side, and many weekends I’m at a DevFest somewhere. I haven’t found the time to run a community as well. Maybe an AI agent could moderate it. If you’ve made something like this work, I’d like to know how.

One thing for other GDEs specifically, and one I hadn’t done before.

The GDE program asks us to add two UTM parameters to every link to a Google developer site in our content: guides, slides, articles. With them, Google’s product teams see how much traffic GDE content brings. It’s counted for the program as a whole, not per person. That’s how our work gets credited, and it’s part of what decides the program’s budget in the future.

Add this to the end of the link:

?utm_campaign=deveco_gdemembers&utm_source=deveco

If the address already has a question mark, start with an ampersand instead. Three examples: a plain link, one that already has a question mark, and one that jumps to a section:

https://antigravity.google/download?utm_campaign=deveco_gdemembers&utm_source=deveco
https://developers.google.com/search/docs?hl=en&utm_campaign=deveco_gdemembers&utm_source=deveco
https://antigravity.google/download?utm_campaign=deveco_gdemembers&utm_source=deveco#section

A few things I found while tagging my own guides:

What goes into a good workshop?

If I put it all in one list, these are my ingredients:

For me, that last one is the main goal of a workshop: to motivate people, to take them with you, and not to bore them. That’s why it matters so much that the workshop runs well, and that you take the time to talk with people in person. I think that’s the best thing you can give them in two hours.

If you’re planning your first workshop, take the Milano guide, the slides and the template repo as a starting point, and copy whatever works for your room.

What made your last workshop work, or not work? I’d like to hear it.

Resources

This is a session.

Everything above is delivered as AI-Native Web Development, Hands-On — workshop, 90 or 120 minutes, in English or German.

Invite me to speakRead the full session