Build Better Web Apps By Teaching Users How to Use Them

Don't get me wrong, I’m a big fan of writing specs, creating UML diagrams, and creating test suites. But, for me, they’re not enough.

This is for two reasons:

• Firstly, without having to teach someone, we're unlikely to think about the application holistically, as they would when they're using it. Instead, as software developers, we all too readily think only in terms of classes, functions, methods, and tests, etc.
• Secondly — and far more importantly — by teaching someone how to use our application, we have to carefully think through what we’re asking them to do. To do this, we have to thoroughly know how our applications work. If we don't, we risk giving instructions that miss essential elements, elements which could cause the user to get an outcome which we never intended.

If you want a hilarious example of giving instructions to someone, and how they can be misinterpreted, watch this video, where a dad follows the instructions that his kids give him to make a peanut and jelly sandwich — literally! If you don't watch it at least three times, I'll be surprised. The kids' reactions are priceless.

If you have even a passing interest in teaching, no matter what the topic is, this is an excellent foundation in why you need to put significant thought and care into how you communicate, what you say, what you don't, the order that you say things, and so on.

Why is teaching so effective?

Getting back to the point at hand, thinking through what we want someone to do and how they should use our application, we get the opportunity to walk in their, proverbial, shoes. Speaking personally, I find that the process helps me think in a very holistic way, almost as though I was the user using the application.

I'm not a psychologist, so am not in a position to really discuss the ins and outs of why it works. That said, I did a little digging and uncovered some really interesting research that sheds light on why this might be the case. Specifically, I found the following quote from, the British Psychological Society:

Students who spend time teaching what they've learned go on to show better understanding and knowledge retention than students who simply spend the same time re-studying.

The article that I drew that quote from has a second observation, one that I find even more compelling than the one above:

The new findings don't undermine the notion of teaching as an effect learning method, but they have practical implications for how the learning-by-teaching approach is applied in education and training. "In order to insure that students and tutors learn and retain the educational material that they have prepared and presented in class, they ought to internalize the to-be-presented material prior to communicating it to an audience, rather than rely on study notes during the presentation process", the researchers said.

You really need to read the full article to appreciate it. However, the essence is that the more you internalise material, such as by learning all about something so that you can teach it clearly and effectively, the better you'll know and retain that information.

That's why I believe that teaching — even preparing to teach an application — helps you build better software. Because to teach an application to an audience, even if that's an audience of only one, you have to know it pretty intimately. Therefore, as you're obtaining that information, you have the opportunity to spot things that are missing, are yet to be built, or are built incorrectly.

I could well be biased, as I write tutorials for Twilio on a regular basis. But this research resonates strongly with me.

Here's how this became crystal clear for me

I've spent part of the last couple of weeks building an IVR (Interactive Voice Response) application in PHP powered by Twilio; one that (if I’m completely honest) had started to take on a life of its own.

If you're not familiar with an IVR, otherwise known as a Phone Tree menu, they're what you encounter, often times, when you ring a large organisation, such as a bank or insurance company. When your call is answered, you hear an automated voice telling you to do things like:

Press 1 to talk to insurance. Press 2 to talk to banking

Without diving too deep into the details, the application that I built is a reasonably sophisticated IVR. It stores the responses to each step (along the way to being connected to a call center agent) in an SQLite database, where the primary key for each record is the call's SID, which is its unique identifier.

When I felt that the application was sufficiently ready, I began writing a tutorial about it, one that steps the reader through:

• How it works
• How to build it
• The benefits of building it in the way that I had

All was going really well, until I came to the tutorial's conclusion. While telling the reader to confirm that the code works as expected, I wrote the following paragraph:

Regardless of the input that you give, when the call ends, in your browser of choice open "http://localhost:8080/caller-input/{callSid}". You'll see the agent dashboard with the caller’s input displayed. It should look similar to the screenshot below.

Here's that screenshot:

Notice the text "{callSid}" in the paragraph above. This is a placeholder for a given call's SID. The reader will need to replace it with a real call SID for the page to load successfully.

However, as I wrote that paragraph, I realised that the application doesn't, actually, display the call SID anywhere. Not in the console. Not in a log file. Nowhere!

It can be retrieved from the Twilio Console, as you can see in the screenshot above. But, to have the reader retrieve the call SID from there would take a bit of instruction to guide the reader through how to do so. This instruction would need to include searching for the Call SID, if the user had been experimenting with the application for some time, resulting in a large list of Call SIDs.

Instead of doing that, I’d prefer to have the application log the Call SID to either a file, or the terminal session where the application was started. That way, it’s trivial to find and equally so to instruct the reader as to where they can find it.

But, every cloud has a silver lining. Right? Thanks to writing a tutorial about the application to teach how it works, I identified the — rather glaring — omission that I'd made, and corrected it.

That's a small look at how you can build better web apps by teaching users how to use Them

I'm not saying that teaching is the only way to truly build great software. However, I am saying that it's an excellent approach that should be encouraged, in addition to the aforementioned UML diagrams, test suites, specs, and all of the other, common, techniques that we use on a regular basis.

Want to get started?

If you'd like to get started, you don't need to land yourself a role where you write them professionally, such as myself at Twilio. You don't need to contribute to sites such as Smashing Magazine, ZDNet, or others of that size either. Start a blog like this one and begin teaching what you know.

If you prefer video or you don't feel comfortable writing, and you have a basic microphone, webcam, and lighting, you could start a YouTube channel instead. Keep in mind that this approach is more time and cost intensive. But, if you're prepared to invest some money in the right gear, and time in setting it up correctly, then video content could work for you. If you're keen to get started, check out this excellent post from Matt Stauffer, where he walks you through what you need to do.

A third approach is to start a podcast, such as the one I started. This is a middle-ground between creating text and video content. You will need a half-decent microphone, but you can pick them up for not that much money. Plus, unlike a blog, you don't need to worry about hosting it, as companies such as Transistor.fm take care of just about everything for you. You just need some recording software, such as Audacity, and a computer that was built anywhere in the last 15 years.

Regardless of the approach that you take, I strongly recommend that you get started. I'm confident that the results will, with time, speak for themselves.