Ellen Beldner

I'm going to spare you the discussion on what Ruby on Rails is and why you'd want to use it. Lots of other people have covered that. A quick word about my background:

• I am a very good HTML, Javascript, and CSS "coder".


• I am a moderately proficient PHP programmer, which I use to create prototypes for usability tests and whatnot.


• I am nigh-on retarded when it comes to hooking a webapp to a MySQL database. Ergo, I usually don't get beyond the prototype stage for a lot of cool webapp ideas I've had.


• I can muddle along in a handful of other languages and frameworks, like Perl, Java, Clearsilver, Struts, and XSLT.


• I have zero exposure to Ruby, Python, Gems, etc.


• I'm good at programming -- thinking in abstractions, being efficient, breaking down a goal into minute logical steps, etc.

My goal: I'm helping a friend create a usability testing infrastructure for his startup. I want to create a website to recruit participants for various studies, let people sign up to be a participant, and do some lightweight CRM of when they were contacted, outcomes, and whether they have already participated in a test.

Requirements:

Participant:

Firstname Surname Phone Country Timezone Email(unique) DateOfSubmission Age Gender Occupation Industry Education ContactForFutureTests? NativeLanguage Status[ New | AssignedToTest | Archived | CompletedTest ] NOTES

Note: (Each participant can have several notes)
Author Timestamp ParticipantID NoteText

Test: (Each test has several participants)
TestID Status[ Active | Complete | Pending ] Date Description ConsentFormURL Compensation PARTICIPANTS

TestParticipant:
CompensationGiven ConsentFormSigned? ConsentFormID

ConsentForm
UniqueID HTML TestID

Note that this is NOT tied to the actual test data in any way -- that's not the point. This app is just to keep track of who we talked to and when. It's a very lightweight CRM.

http://www.nytimes.com/2007/03/25/business/yourmoney/25Proto.html?_r=1&oref=slogin

Summary: Let advanced users hack on your products. They will come up with innovations that you didn't think of.

This stands up nicely to an economic interpretation too: If someone is willing to take the time to hack around and build something that wasn't part of the spec, that means that they're willing to spend capital to have that functionality. Which means it's some sort of market opportunity.

Enterprise software can often be maddening like this: companies sell their software for $200k + and they want to be gatekeepers and prevent customers from getting into the code -- they want to preserve the mystique or something. But often they just end up being roadblocks to customer happiness. Like, I bet if we could have hacked on Oracle Calendar rather than having to build our own totally separate version, we'd be vastly more advanced than either system ends up being. Good, complex software takes time (a lot of time) and figuring out how to build on the accumulated knowledge of others (represented in code)

Unfortunately, the article puts this technique in opposition to "traditional" anthropological design processes -- which often aren't well-integrated anyway. There's absolutely no reason why you can't derive benefit from both techniques.

When it comes to discussions about writing software specs, I really like to quote Sen-Rikyu, the master of the modern Japanese tea ceremony: "Tea is naught but this. First you make the water boil. Then infuse the tea. Then you drink it properly. That is all you need to know." But if you know anything about the actual practice of the tea ceremony, there is -- for laypeople who have not mastered the Zen of simply boiling the water and infusing the tea -- an immensely complex protocool, replete with symbolism that must be adhered to.

Writing specs is simple. All you do is document what has been decided and capture known uncertainties, and underlie everything with a giant disclaimer that until the code is written you won't know exactly how it's going to work.

In fact, perhaps we shouldn't think of specs as specifications of software. They are specifications of goals for the software.

I'm about to start working on a UI spec for some upcoming changes to the Google Base UI. I'm always looking to improve, and this is a pretty complex series of workflows that we have to get just right. So I want to make sure that I capture and communicate all of the decision points that I've traversed up until now, and that I specify behavior that may not be fully obvious in the prototype that I built.

Let me highlight some key concepts from that last paragraph: Capture. Communicate. Spell out corner cases.

So I searched for write UI specs. The first result is 37 signals explaining why specs don't work. I read this type of article -- along with some Agile and XP techniques -- as a radical overreaction to the other extreme (of overplanning and presuming you can actually precisely specify software on a piece of paper before anything is written). In that sense, the 37 signals article is irresponsible. It's speaking to a particular historical context of software engineering without acknowledging that there are a lot of ways that specs can be written, usefully, in the context of more modern software engineering practices. Moreover, when you're not working at a small startup, it is irresponsible to not write specs. Specs help other teams anticipate and plan for what's happening down the line, and when you don't have the same 10 people doing everything -- when you have a marketing department, a customer service team, writers who have to do help documentation -- you need to let them know as early as possible what you think is coming down the pipe, so they have maximum time to plan their own resources and schedules.