“Oh noooooo…”
It was a cool Sunday afternoon. My wife’s disappointed exclamation punctured the calming static of Singapore’s November rain. I looked up from the article I was editing. Pratibha had recently taken a liking to Sudoku, and was starting her daily puzzle. Our dining table iPad’s browser tab had refreshed itself in the middle of her pre-game ritual of copying down the puzzle onto her notebook. The puzzle was lost, and a new one had appeared, nestled in a collage of flashy advertisements.
“It’s okay,” she said in a tone of resignation. “I can use the new puzzle.” And she started copying it down.
But gears were already turning in my head. I had just observed a real problem. A small, concrete problem that I, as an engineer could possibly solve!
As Pratibha started work on the new puzzle, I loaded up the same website on my laptop. The page loaded quickly, but before I could place any numbers, the puzzle grid faded to black behind a large, flashy modal offering unique rewards for joining an online Sudoku event. To the left, a tall banner advertisement flashed into view.
“See where 15 minutes can take you”, the animated words faded in. It was an advertisement from Singapore’s National Library Board that wanted to encourage more Singaporeans to read books. A rugged video game character pored thoughtfully over a tattered tome, but before I could identify the character, the ad slots refreshed and were replaced with an ad for a stock broker, offering rewards for new sign-ups. I’d already forgotten what I’d come to the page for.
I closed my eyes to wrestle my attention back and tried to recall my train of thought.
Sudoku should be a solved problem, I reasoned. There are a thousand apps out there — both native and web-based — that will give you a free puzzle. The logic behind them can’t be that complicated. My brain forked off a thread in the background planning the puzzle layout and the process of generating one.
The world probably doesn’t need another Sudoku app. Don’t waste your time. said the cynical corner of my brain.
But you’re not building for the world anyway, the excited builder in me interjected. You’re building for an audience of one. And if it’s on your website, you can add exactly as many features as your wife needs and stop exactly there. You can keep it well tended, like a craftsman. This thought was considerably more convincing.
I opened my eyes, ready to spin up the new project. The ads on the page had changed again. Pinduoduo was now in Singapore apparently. I closed the tab before I had to wrestle with my attention again.
In the days that followed, I observed my wife’s Sudoku playing habits more closely.
She started her game by copying the puzzle from the website onto a neat grid in her notebook, drawn in ink. She’d then ink in the clues before switching to a pencil. Solving in pencil made it easy for her to erase and back-track when mistakes were made. And mistakes were definitely made, as I’d find little drifts of eraser crumbs scattered around the notebook like spent shell casings after a battle. She also always made a note of the time near the puzzle grid before starting work to measure how long her solutions took. From time to time, she liked to share a photo of the solved grid.
I felt like I had identified my initial feature list. The most important feature, from what I saw, was that the app must not lose the puzzle through page refreshes and reloads. And if you do end up losing the puzzle somehow, then there must be an easy way to retrieve it. The app also needed a timer and an easy way to share an image of the puzzle.
Version 1
The first version of the app took a few days longer than the cynical corner of my brain had accounted for. It turned out to be not so trivial to make sure that each puzzle had exactly one solution, and that easy, medium and hard puzzles were actually easy, medium and hard.
To make sure each puzzle had exactly one solution, I decided to work backwards. The app started with a completed puzzle, then removed numbers. After each removal it tried to solve the puzzle using techniques a person would use. Any removal that produced a puzzle that could not be solved was discarded.
Making each puzzle the right difficulty level was a little tougher. In the end, I decided to grade the puzzle difficulty on which tricks you needed to know. For easy and medium puzzles, the basic strategy of finding a square where only one number fits should work. For easy puzzles, the generator stops once it’s down to 38 clues. There should always be something easy to fill in. For hard puzzles, the generator allows more tricks, like spotting two squares that must share the same pair of numbers. And if a hard puzzle turns out to be solvable with simple moves alone, the app discards it and starts over.
The whole thing lived on single page on my website, with the puzzle generation and solving logic run entirely within the browser. Below the large Sudoku masthead, tucked beside the puzzle code and difficulty level, sat a timer that started counting as soon as you loaded the puzzle. I clicked away to another tab and came back. The timer had paused, and started up again as I looked at it. Good.
I tested the notes feature next. I had tried to replicate my wife’s playing style. The puzzle had a separate “Notes Mode”, activated by pressing the N key on your keyboard, or by pressing the “Notes” button in the keypad stacked beside the puzzle grid. Numbers entered in Notes Mode appeared as light small digits along the corners of each cell, as though written with a lightly pressed pencil. I also added a little flourish of my own: when you placed a number in a cell, any note ruled out by the number in the box, row or column would disappear.
Now for the big test. I entered a few numbers, closed the tab, waited for a few seconds and pressed ⌘ + shift + t and watched the page re-load from scratch. It was exactly as I’d left it, timer included. Every move was saved to the browser’s localStorage so that you could close the tab, refresh it or come back to it days later and still pick up the puzzle exactly where you left off. As the page finished loading, the timer started ticking again. The game even survived a browser back / forward button. Perfect.
The bottom of the keypad was focused on the social aspect of the puzzle. A short code (like M-6CAA45) can be used to generate the same puzzle grid on any device. The first character represents the difficulty level (M - medium). The last six characters in are written in Crockford’s Base 32, a compact human and machine readable alpha-numeric code. The code is the seed for a small pseudorandom number generator (Mulberry32) that drives every choice made while constructing our puzzle grid. So the same code builds the same puzzle on every device.
The “Copy Link” button copied the game URL along with the code to your clipboard, so you can save it, or share it with someone else who wants to attempt it. You can even scribble the puzzle code somewhere if you like and enter it in the text box at the bottom and click “GO” to retrieve a puzzle. Basically, you have to try really hard to lose track of a puzzle now. The “Share Image” button generates an image of the puzzle in whatever state it’s in when you tap the button, ready to be shared in a group chat.
I methodically worked my way through the various buttons and features I’d implemented, and nothing seemed obviously broken. It was ready for handoff.
“Oh my god! This is amaaazingggg!!! Woooowww!” she said when she first loaded up the page. I’d managed to impress the target audience on the first try!
Version 2
The feedback trickled in as she played.
“Oh, the Easy, Medium and Hard buttons don’t start a new puzzle.”
Fair enough. I’d made it so that you had to select the difficulty level and press “New Puzzle” to get a new one. I didn’t want her to lose progress from an accidental tap. In retrospect, this was definitely a bit counter-intuitive. And hadn’t included a user manual anywhere on the page. The only bit of explanatory text was a small, easy to miss “why” next to the game timer that explained why I decided to make the app. But the obvious fix — just starting a new puzzle when you tapped a new difficulty level — would bring back the “Oh noooooooo…” that started it all. I decided to give each difficulty level its own save slot instead. Tap “Hard” and you get a fresh Hard puzzle. Tap back to “Medium”, and the puzzle you abandoned comes back, exactly as you left it.
Guess there’s a balance between playing it safe and having a good user experience. I pushed out the update.
Version 3
A few days later, the next comment came in.
“The notes disappear when I place a number. I don’t like it.”, she scrunched her face into that familiar frown she often wore when something was annoying her.
I’d built that one in on purpose! It was thoughtful flourish! After you placed a number, the notes are surely a distraction? I thought. But my internal voice was also excited. If your user is invested enough to start giving detailed feedback like this, they like what you made (or they really like you, or both).
“I feel like when the notes disappear, things are sliding out of my mind.” she continued, “When I play, I cross out the notes. See?”
I squinted at the puzzle grid on the notebook she was holding up. Seems like I had not been observing closely enough. She was right. The completed puzzle grid was filled with little crossed out notes in the cell corners and edges. When you play on paper, nothing disappears until you erase it. Her pencil marks were a record of her thinking process. By erasing the notes on the app, I was throwing away the thinking. No wonder she felt like the information was sliding out of her mind.
The next update was pushed out in a few days. The notes now crossed themselves out when she placed a number. Her thinking was safe.
Version 4
The gaps between feature requests grew longer; I squashed a few bugs here and there meanwhile. After a particularly long gap, I took the liberty of adding something that scratched my itch to build features nobody had asked for, a finishing touch of my own: a small animation that spread across the grid like a wave when the puzzle was completed.
A few mornings later, I was having my first coffee of the day, and Pratibha was playing her morning puzzle on my website. She’d been using it every day since the release. She looked up at me after the puzzle. “I love the app,” she said. “It’s perfect now. No more changes needed.”
Finally, product-market fit.
For three days.
Version 5
A WhatsApp message arrived as I was having my lunch. Pratibha was in the middle of a Hard puzzle. “Sudoku app feature requests.”, read the notification preview.
Need Redo button. The first bullet point read. It continued.
Need a way to highlight what I’m undo-ing (eg a red circle on the number I’m placing or removing)… need this because I can’t see what I’m undo-ing.
And one more, marked optional: a notepad that records her moves using row and column names, like a chess game.
It was nice to receive such a well organized feature request ticket with bullet points. She’d been working through the Hard puzzle, made a guess that went wrong, and tapped Undo to back out of it, but Undo had changed the grid without showing her where.
“I should have added this already,” I thought. “What kind of app lets you undo but not redo? Maybe I tried to lean too hard into the paper based workflow.” And the app definitely needed to show you where the undo / redo was happening. I could imagine that once the many numbers and notes were filled up, spotting where the action happened could get difficult.
The optional request for a row and column notation for every move, was a nice touch too, and one I hadn’t thought of at all.
Definitely worth including. I thought.
Most chess apps do the same thing and it’s quite useful to see the path you took to victory (or defeat). Since the app already saved a history of every move to localStorage this was just a matter of having the right UI element to display information that we already had.
At this point I stopped declaring product-market fit. It’s just “done for now”.
Then, one weekday morning, as I was working through my tasks at work, my phone buzzed. Pratibha had shared the puzzle she’d just solved.
“227 moves 😄,” she said proudly. The new move counter was a hit.
More messages trickled in.
I accidentally clicked on back
While playing
And then went forward to this page
And everything was as is
Including the timer
Thank you 🥹🥹🥹🥹
You saved my work
It’s a very thoughtfully designed app
She’d run my big test without knowing it. The app had survived a real field test and my most important feature was working as intended. I put my phone face down on the desk and went back to my morning tasks, a light smile on my face.
Thoughtfully designed. I’ll take that.
If you’d like to try out a Sudoku puzzle app designed for one person that saves progress locally, survives page reloads, refreshes and back / forward navigation and has no distracting ads, you can try it out on my website.
Correspondence
Reader Comments & Discussion
No comments yet. Be the first to share your thoughts.
Join the Discussion