An excerpt from my book, Programming Beyond Practices.
At the end of Part I, you and your pairing partner Samara sent your client a very early ‘live wireframe’ of the music recommendations tool you’re working on:
This first step was almost microscopically small, and you were concerned that the client would not understand why you wanted to share it, but Samara suggested that even the tiniest steps could lead to valuable feedback and problem spotting.
She was right! And so the story continue here…
Discuss defects, but be pragmatic about repairs
Hello developer friends!
I just got the chance to try this out. On my laptop, the page looks pretty much like what you showed me in Samara’s sketch, so no complaints there.
I also tried to load the page on my phone, but things look awkward there. All of the videos take up the full width of the screen, and the recommendations are displayed in one long column rather than being shown side by side.
We definitely don’t need to make this thing look beautiful any time soon, but it seems like we should at least try to make sure all the recommendations are visible on a single screen, rather than having to scroll past a bunch of full-size videos.
Is that something you think you can do something about?
As Samara predicted, something did manage to slip through the cracks, even in this extraordinarily simple first iteration. It’s impossible to entirely guard yourself from making mistakes, but how you respond to them is critical.
You know that you can’t leave the mobile UI question unanswered, but you don’t want to dwell on it either. A reasonable response would be to draw up a fresh wireframe to communicate what the site should look like when rendered correctly.
Samara begins looking at a few popular video-based sites on her phone and finds that several of them use a common layout. She then sketches up something similar, but stripped down to the bare essentials.
You send the wireframe along to Ross, and then spend a few moments talking over next steps with him:
Ross: Thanks for the drawing! It looks like a decent starting point.
You: That’s great to hear. Now we have a decision to make: do we work on fixing the mobile layout issue right away, or do we put it off until later?
Samara and I think that it may be worth implementing some useful recommendations functionality first, and then revisit UI questions down the line.
That said, if you feel that a mobile-friendly design is essential even during the early stages of gathering feedback, we can take care of this before we move on.
Ross: Is this kind of issue harder to fix later than it would be to deal with up front?
You: I don’t think so. Most of the work on the recommendations system will be under the hood, and so the desktop UI shouldn’t need to change much. And if for some reason we do need to make major UI changes, we’d need to go back to the drawing board for the mobile sketches anyway.
Ross: OK, let’s wait a bit then. If any of our early testers complain about not being able to easily use this on their phones I may change my mind, but we can wait until we start collecting some feedback to worry about that.
Whenever you find a flaw in your software, it is tempting to drop what you’re doing to work on repairs right away. But in the exploratory stages of a project, it’s important to balance the cost of each defect you encounter with the cost of the time it might take to fix it.
In this particular case, time not spent on dealing with minor style tweaks on mobile is time that could be spent exploring the music video data sets and trying to come up with some recommendations rules. But by putting together a rough plan for how to fix the issue and communicating your ideas to the client, you eliminated some risks up front without having to invest a huge amount of effort.
Check your assumptions early and often
Early conversations with Ross have hinted that he is just trying to build something fun for his music community, a much easier problem to solve than “trying to create the most sophisticated predictive music playing service in the entire world!” or anything else along those lines.
However, it always pays to check assumptions on things like this as early in the process as possible. The initial wireframe sketches focused on what the UI for the application might look like, but now it is time to discuss how it should work:
You: Now I’ll ask a more technical question…
What kind of rules should we use to implement recommendations?
Ross: Oh… hmm… I was hoping you might have some insights into that. Up until a few weeks ago, it didn’t even occur to us that this project might be worth working on, so it isn’t something we’ve done a ton of research on yet.
You: Well, there are a bunch of options here, ranging from basic category matching to very sophisticated approaches involving machine learning. It really depends, and although we could probably help you get a jump start no matter what, it isn’t an area we specialize in.
Ross: I’m not sure if it’s helpful, but our blog posts are all curated lists (e.g. “Ten great Miles Davis tunes you’ve probably never listened to,” “A collection of live hip-hop performances from 1980s New York,” “Family favorites for the Christmas season”).
Our goal with this recommendations tool would be to help cut across these lists so that the listener can find other things they might like. So, for example, they might be listening to a 1980s hip-hop recording that was live in New York, and then we’d find other songs by that same artist, or we’d find other 1980s hip-hop songs, etc.
You: OK, this gives us something to think on, thanks. I think Samara and I might let these ideas percolate for a little while, and then we’ll have more to show you sometime tomorrow. Does that sound good?
Ross: Absolutely! Thanks for the work so far; this was fun.
This conversation confirms that a simple recommendations system might be good enough and that Ross is flexible about its implementation details. You may have lucked out in this case, but if he had a more complicated idea in mind, it would have been better to find out sooner rather than later. So it never hurts to ask!
Limit the scope of your work as much as possible
Everything up until this point was just about finding an entry point into the project, but now it is time to roll up your sleeves and get some real work done. There are still plenty of unknowns to work out, and just studying Samara’s original sketches for a few minutes generates many questions about implementation details:
These questions crop up in a non-linear fashion, but before you can do any useful work, you’ll need to prioritize them somehow.
Of the five important issues you and Samara have identified, two appear to be low-hanging fruits: how to generate embed codes for videos, and how to construct URLs for thumbnail images.
You pull up the music blog that Ross manages and check to see what video hosting service they’re using. You also click through a few posts and check their source code to see how things are structured.
“Most posts use only embedded videos from FancyVideoService. The embed codes follow a standard format; the only thing that differs from video to video is its unique identifier.”
“How about thumbnails? What do those look like?”
You hesitate for a moment, and then your clicking on various blog links intensifies, until you are convinced that you aren’t getting anywhere.
“It doesn’t look like they actually use thumbnails on their site. Everything I’ve seen so far is just embedded videos. So I guess we’ll need to look that up.”
You search the Web for a few minutes, but don’t find any official documentation from FancyVideoService about how to grab thumbnails for their videos. You do, however, find a blog post that describes the URL format they use internally, and it’s easy to generate these links using the same unique identifier that is used in video embed codes.
You manually create a few thumbnail URLs based on the videos from Ross’s blog. They seem to work fine, although it is questionable whether this is actually a supported use case. For now, you hope for the best, but you’ll need to get in touch with FancyVideoService to confirm that this approach is legitimate before the project wraps up.
With these chores out of the way, you can go back to the more subjective questions that came up when you were reviewing the mockup: what data to collect about each music video, how to go about storing that data, and how to use the data to generate useful recommendations behavior.
You and Samara start to talk through options, but then realize you’re getting too far out into the weeds. So you go back to the classic question: “What is the simplest thing that could possibly work?”
After a few moments of quiet rumination, Samara gets a burst of inspiration.
“What if we started with artist matching? Based on whatever video is playing, randomly pick a few more songs by that same artist.”
“Good idea. I think we’ll need something more complicated before Ross sends this out for feedback, but I’m just really itching to get something on the screen that we can interact with right now.”
Artist matching is an easy starting point, because all that is needed are video identifiers from FancyVideoService, song names, and artist names. If you grab a couple dozen songs from Ross’s blog, that would be a decent sample data set to work with.
“What should we do about data storage? Should I go ahead and provision a—”
Samara abruptly cuts you off in the interest of keeping things simple.
“No need for that yet. Let’s hardcode a sample data set as a bunch of arrays, and walk over those to generate the recommendations.”
“You know that won’t last us that long, right?”
“Doesn’t matter. It doesn’t have to!”
Samara is on a roll, so you ask her to do the coding while you piece together a handful of song names, artists, and video identifiers.
Fifteen minutes later, the two of you have something that looks halfway decent:
Just to show signs of progress and to hint at things to come, you drop one last note to Ross before wrapping up for the day:
You: Hey Ross, if you check out the website you’ll see that we now have something up and running that kind of looks like a music recommendation system. It’s very limited at the moment (only does artist matching), but thought it’d be fun to show you what we’ve been able to put together so far.
Ross: Whoa! Nice work. It definitely feels good to be able to interact with this rather than just looking at placeholder images, and it seems to be working mostly how I imagined it would in my mind.
I assume you’ll be adding some more interesting recommendation behavior tomorrow? It doesn’t need to be fancy, but it’d be nice to go beyond just artist matching.
You: Absolutely. We’re still giving that some thought, but we will be in touch tomorrow with more to show you.
Ross: Great. Thanks again for working on this. I’m super pleased to see an early version of this idea take shape in the span of a single workday.
The basic walking skeleton1 that you and Samara have put together will increasingly become more interesting to work with in future iterations.
While the first day of work consisted of getting the various moving parts into position, it has put you in a good place to begin exploring the real problem you are trying to solve. Had you attempted to jump straight into thinking about how to solve the full problem, it would have been harder to find a starting point, meaning much more stumbling along the way.
With not much time left on the clock for the day, you decide to spend the afternoon taking care of minor chores, reading blog posts, and using your phone to chase imaginary animals in exchange for imaginary Internet points.
To continue reading, you can check out Part III here.
But if you loved this free sample, please buy the full book and/or read it on Safari instead. That’s the best way to let an author know you appreciate their work. 🙂
Thanks for reading!