I spent three weeks building a puzzle game. Then I spent six weeks writing its tutorial. That ratio should tell you something about how badly I got this wrong the first time.
The game was simple — six colored tiles, a target color, you swap tiles to match the target. I'd prototyped it in an afternoon, polished it over a weekend, and by day five I had a playable build. I threw it at a few friends. They had no idea what to do. One of them clicked around randomly for about thirty seconds, said "I think it's broken," and closed the tab.
That stung. So I wrote a tutorial.
Version 1: The Wall of Text
I dropped three paragraphs of instructions at the start of the game. Bold headings, bullet points, a diagram made in MS Paint. I was proud of the diagram. It had arrows.
The next tester opened the game, saw the text, scrolled past it without reading a single word, and clicked the swap button seventeen times in a row. When nothing happened, he said the colors were lagging.
I took the diagram personally.
Versions 2–4: Overcorrection
Version 2 was a highlight overlay — the tile you need to swap would glow, and a pulsing arrow would point at the target zone. I thought I was being clever. What actually happened was that testers stared at the glowing tile, waiting for something else to happen. They didn't swipe. They watched the glow like it was a screensaver.
Version 3 brought in a progress bar. "Swipe 5 times to unlock the next level." This created a new problem: testers swiped randomly, not caring about colors, just trying to fill the bar. They learned nothing and complained that level 2 was too hard.
Version 4 was a video. I recorded a 45-second screen capture with voiceover, embedded it, and watched in horror as exactly zero testers clicked play. Not one. The video sat there like a museum exhibit that nobody visits.
Versions 5–6: Getting Closer
Version 5 was where I started to understand the problem. I removed all text and all instructions. The first level had only one valid move — you literally couldn't make a wrong move because the game would only register the correct tile. Testers figured it out in about fifteen seconds. That was the first time anyone completed the tutorial without getting frustrated.
But they also felt manipulated. "The game played itself," one tester said. "I didn't learn anything, I just tapped where it wanted me to tap." Fair criticism. The tutorial taught the action but not the strategy.
Version 6 added a second tile to the first level. Two possible moves, one correct, no instructions. The error rate was high — about 40% of testers made the wrong choice and got stuck. But the ones who got it right understood the game instantly. The ratio was wrong but the approach was working.
Version 7: The One That Worked
Version 7 combined the constrained-first-level approach from version 5 with a single line of contextual text that appeared only when the player hesitated for more than three seconds. Not a wall of instructions — a short phrase like "match the color" or "swap toward the goal." The text was never the same twice, and it only showed up when you needed it.
Testers went from confused to competent in about twenty seconds. Nobody skipped the text because the text appeared exactly when they were looking for guidance — right when their finger stopped moving and their brain started searching.
The tutorial completion rate went from 22% on version 1 to 94% on version 7. Average time to first correct action dropped from 47 seconds to 12 seconds. I have a spreadsheet with all the data and I look at it sometimes when I'm feeling down about a different feature that's not working.
What I Learned
Version 8 was actually a slight regression — I added a visual flourish that made the tiles pulse on correct swaps. Test scores dropped by 5%. I cut it and kept version 7. That's the version that shipped.
The thing I keep coming back to is this: nobody wants to learn your game. They want to feel like they already know it, and they want the game to quietly confirm that feeling. Every word you add to a tutorial is an admission that your game isn't intuitive enough. Every arrow, every popup, every "Tap here to continue" is a tiny failure of design.
The best tutorial is the one that disappears. And that only works if the game underneath is honest enough to teach itself.