Most of us hate to write specifications. They're seen as an onerous task and, for many small projects, an irrelevant one. Whether or not the task is onerous is purely a subjective opinion. Whether or not the specifications are irrelevant is not subjective.

Case in point: a simple form-to-email script.

My company is offering a product that has generated a huge amount of interest. In order to handle the unexpectedly large demand for information, we wanted to include an information request form on the Web site. I happened to hear my name mentioned by my boss and wandered over to catch the tag end of a conversation that was about what I needed to do. Coding a script that captures about 20 form fields is not particularly difficult. Untainting all of them can take a bit longer. My boss knows that I use a form-parser that I've written to automatically generate the form handling code. Thus, he assumed that it would take me about 15 minutes to write the script.


It actually took me about three hours, mostly because no specifications had been written. I was told to simply write a form-to-email script that would send us an email with a request for 8 by 10 color glossy photos (thanks, Arlo!) of our product. I was sent the link to the HTML form and that was my complete specification. Nothing, of course, was in writing.

Now many of you are probably thinking, what's Ovid blathering about? That's a piece of cake. In reality, it's a bit more work than it appears on the surface. Further, because no specifications were given and because the people who dreamed up this little assignment took off for a couple of hours afterwards, I was left to come up with the specification on my own.

I decided that the form had to be "sticky" (information filled in if the user is sent back to the form) because the user may not supply all of the necessary information. I went to the person who designed the form and requested a confirmation page (one would think they'd get the hint, since I request this for all pages where there's no way to verify that an action had really occured). Further, since I try to be sensitive to privacy information, I made all contact information, except for the contact name and address, optional. We needed to mail a brochure, but if someone doesn't want an email or follow-up phone call, then they can "opt out". I also realized that the server this was to be on didn't have Template Toolkit installed, but did have HTML::Template. However, no one here uses HTML::Template and I didn't have the authority to just go out and install the Toolkit. What do I do? Use "HERE" docs? Ugh!

On my first iteration of the script, I reluctantly used HERE docs because I had no idea what was intended. I got the confirmation page from the designer and had everthing running fine. Sticky fields, useful error messages about required fields, and a slick confirmation page were thrown together pretty quickly. Then my boss got back.

As it turns out, there were three completely different forms that I needed to capture information from. My required fields were wrong as we needed phone numbers and email to bug the heck out our potential customers with. And I could forget about the HERE documents as they want Template Toolkit on that server, anyway. I had a modest amount of my code that was now junk and had to be rewritten. A simple form-to-email script that should not have taken very long wound up taking several hours to write because I was forced to guess what was needed. Had specifications been written, I wouldn't have wasted my time and I could have gotten back to my regular work much sooner. The next time you're thinking about skipping clear specifications, think about this. If it's more complicated then the script that I described, how many hours are you going to waste?


Vote for paco!

Join the Perlmonks Setiathome Group or just click on the the link and check out our stats.