Fusebox

Our House
Everyone who has ever developed an application is all too familiar with the problem of clients' shifting notions of what they want and need in an application. I sometimes think the process of building a web application is much like building a house. The difference — the big difference — is that while most houses have architects defining what the house will look like before it is built, most web applications don't.

Maybe it's because as developers, we like to develop and so don't spend much time on the planning phase; or maybe it's because we've been through endless planning and requirements gathering meetings, only to have the results thrown out the door as the client began tinkering with the application.

Whatever the reason, we developers seem to have gotten used to the situation where, continuing the house-building analogy, we're ready for the client to move into the house — and pay us for it! — but find the client walking around the house, saying, "Gee, it would be nice to have a deck off the back," or "You know, I think a wine cellar would be really great."

It's enough to make you want to go into a calmer profession. Air traffic control, maybe.

I recently completed a large-scale, very complex ecommerce website for the nation's largest furniture retailer, www.roomstogo.com, which was featured on Allaire's website a few months ago. Gravity Free, a web design firm in Sarasota, Florida, which had been awarded the project, asked me to architect and head up this project. When I first met with Scott and Ray from Gravity Free, they told me, "This is the biggest job we've ever done and we want it to go well. Really well. That's why you're here."

Bummer of a Birthmark
Someone once sent me a cartoon by Gary Larson of The Far Side fame, showing two deer in a forest. In the background, you can see hunters lurking. One deer is looking at another whose fur has grown so that it closely resembles a bull's eye target. "Bummer of a birthmark, Hal" the first deer commiserates. For some reason, as Scott explained the stakes, I thought of the cartoon.

The project took about six months from beginning to end. And, I'm happy to say, the site launched successfully and both client and developer were happy. But I've been involved in some projects that were failures. Spectacular failures, even. And those were really the inspiration for discovering/developing a methodology that served us so well on Rooms To Go.

Working very hard with other people also working very hard should produce good results — right? OK, throw in smart people working hard, and you've got a lock on success. Why this is so completely untrue I have no idea.

The Blame Game
What I do know is that when good results don't seem to keep track of the hours expended or the IQ points of the people involved — and when those fickle good results don't show up, all the participants suddenly develop remarkable skill at The Blame Game. Former colleagues vilify each other and no one is happy.

You have to say one thing for pain, though: it focuses the attention. In fact, I've become something of a failureologist. When something fails — even something fairly small — I want to know why. It's not that I enjoy failure — quite the opposite. I think I must be like the man deathly afraid of snakes who becomes a herpetologist in order to better keep his eye on his enemies.

What I've learned is that failure in software projects is built right into the system. In fact, it's remarkable when things don't fail. One might even grow metaphysical and say there would be something wrong with the cosmos if failure wasn't a common event. But judging from the software failures we do have, all is well in the universe.

The Problem: Requirements Gathering
The problem lies in requirements gathering. In fact, even the name, requirements gathering, is a problem. It makes it sound as though requirements are scattered about and all that's necessary is to bend down, pick them up, and place them in a basket like so many primroses.

Ah ha — you think I'm exaggerating, but how many times have you seen an app deployed where the client spontaneously exclaimed, "Now that's exactly what I thought it would be like!"? Not many? Well, I'll grant that we don't use baskets to gather requirements. We use something far worse — meetings. And if that were not deadly enough, we memorialize those meetings in written memos.

Whistler's Mother
Imagine that you are a gifted painter but one who, remarkably, has never seen the painting, "Whistler's Mother." You are commissioned to reproduce it for the Musee d'Orsay, where it hangs on exhibit. But rather than being able to view it, you'll be given a 75-page "Specification for Arrangement in Grey and Black No. 1 by James Abbott McNeill Whistler." You open the tome to read:

"The painting shall be oil pigments on a canvas 56 3/4 x 63 3/4 in...."

It goes on. And on. Finally, you make it through the entire volume. Do you now understand the requirements? Are you ready to start painting?

If you think this a perfect example of foolhardiness, well — I agree. I don't think anyone would imagine that, as talented as you are and as hard as you work, your painting will be much to your client's liking. But don't we do something similar when we undertake to build an application that neither we nor the client — the ultimate judge of that application — have seen? Do you see why I say failure is built into the system?

The Antidote
There is an antidote for such toxic "requirements gathering" and that is what this article is about. If I've delayed talking about it for so long, it's because I hope to impress on my appreciation of the problem.

This is important because the solution itself is very simple — so simple you may be tempted not to see it as a solution at all. But I assure you, as a fully-fledged, card-carrying failureologist, that a solution it is — and I'm hoping you'll believe me enough to try it out yourself. Once you do so, I'm convinced, you will have all the evidence you need.

The solution is not to rely on those paper requirements at all — or perhaps more accurately, to trust them only to guide your first steps in building a wireframe, which itself forms the basis for the ultimate solution, the prototype.

If you're not familiar with the term, "wireframe", I use it to describe a barebones version of the application that represents every aspect of the fully functional version, but does no real processing of information.

Every page that will exist in the application exists in the wireframe and the user can click through every possible route through the application. There are no graphics of any sort. There is no attempt at page layout or user interface issues. What that leaves is a page that defines what its job is and what paths lead out of it. The premise of the wireframe is simplicity.

In its initial phase, it looks just like Figure 1 — completely unadorned. Later (and in the next article I will detail how), we integrate DevNotes, a system of threaded, context-sensitive notes that both developer and client use as a means of communicating — a kind of "forums" for the project.

The Wireframe
The wireframe runs on the web, so that anyone can check in and see its current state as well as the issues still unresolved. The links take the user to a different section of the wireframe that has its responsibilities laid out as well as links to other sections.

Maybe it's a Pavlovian thing, but clicking on an application seems to bring out the "Gee it would be nice" syndrome. This is just the right time for this to come out — before you've invested any time and money in code. This is something you can welcome — after all, you're now really discovering user requirements.

As we use DevNotes to "talk" back and forth, the shape of the project is very likely to change, perhaps even very considerably. Things we thought were important (and maybe feared would be very difficult) may turn out not to be important to the client at all. And, of course, a lot of things the client wants we have never considered.

Every time the specifics changed, I had to rework wire frame had to be reworked. I began wondering — if the essence of wireframes is simplicity, why aren't they simple to build? I appreciated that hand coding the simple HTML was saving us all sorts of expensive coding time, but I didn't appreciate having to continually redo the wireframe, sometimes on a daily basis.

I began noodling with an idea. What about an application that would make creating a wireframe very, very easy. What would it look like? How would someone use it?

Work With a Wide Variety of Projects
I wanted to develop something that would work on a wide variety of projects; I didn't want to ever go back to the old development cycle, ending up in a spirited round of The Blame Game. I wanted something that didn't require any coding, if possible. After all, would we always want a coder to be doing requirement gathering?

I knew I wanted to store the information in a database and create the pages dynamically, so I experimented with creating forms that a project manager could use to create their own wireframe pages. It took too long. It was hard to get an overall sense of the entire application when you only saw the information on a single page.

The Virtual Wireframe
What I finally came up with was something I dubbed the "Virtual Wireframe". The wireframe designer builds and edits a single master file. It's a simple text file, designed to make changes very easy.

Every time the wireframe is run, this file is parsed and information written to a database. The database is then read and displayed, including links to other sections of the wireframe.

The master file (I gave it a .wir extension) is made up of individual sections. Each section defines a wireframe page.

[Find Books]

Responsibilities: I return the results of the search based on the search string that was passed to me. I check both the local and the connected databases. If I find more than 5 matches, I select the ones that have the lowest prices.

buy a book = Order Form

another search = Sales Menu

A section begins with the page title set within square brackets. When the wireframe is rendered, this will be displayed at the top of the page.

Next, each section has two types of entries. One is a responsibilities type. This is an idea I took from Fusedoc and it lets all of us see in simple, plain English a description of the page clicked on. It starts with the word "Responsibilities", followed by either a colon or equal sign that separates it from the actual text description.

The other type of entry is a link. These appear as hypertext links and let the client click through the application to other wireframe pages. In Fusedoc terminology, these would be eXit FuseActions (or XFAs). These have the format descriptive name = page name. When rendered, these turn into hypertext links that the user can click.

To add a new page, you add another entry. To create a link to another wireframe page, you add to the links of an entry.

[Order Form]

Responsibilities: I am passed a listingID that tells me (1) where the book is and (2) how much it costs. I automatically provide the store id of the user and let user decide how shipment is to be handled ( Overnight, Second day, economy ). User puts in customer's name, address, phone number and payment type (cash, credit card, check). If credit card, user enters credit card number, name, and expiration date.

another search = Sales Menu

submit form = Process Order

[Process Order]

Responsibilities: I try to authorize the credit card. If I do, I enter an order into the Orders table, email the selling store (if remote) and provide an invoice to give the customer.

simulate failed credit card auth = Order Form

simulate successful credit card auth = Thanks

The rendering code remains the same for any project. Only the .wir file changes — and this file format is so simple that anyone can use it. I've used this where we had non-coders build the wireframe and everyone was able to pick it up immediately.

The .wir file can be quickly scanned to see the scope of the application as a whole. It's very fast — so you can make changes and additions while in a meeting (real or virtual) and the changes occur instantly.

Doesn't Solve All Problems
I don't want to leave you with the impression that wireframes solve all problems. I still have to remind clients when I need information from them. I still have to keep after them to check out changes.

And even when we are all convinced that the wireframe is done, we still don't start coding. As I mentioned before, the wireframe becomes the starting point for the prototype — but that's another story for another article.

Still, even with those disclaimers, I will say that wireframes have made an enormous difference in assuring the success of a project and making the difference between the kind of high-profile success that www.roomstogo.com was and some of the failures I've seen. And that, as you may well imagine, is music to a failureologist's ears.

You can download the code for the virtual wireframe from www.halhelms.com.