Coming Out of the Tunnel
Chet and I have been busy on various gigs and things, plus wasting a bit more time than we might ordinarily do, and we think it is time to do something potentially useful and interesting. Chet observed that I’m really bad about updating my software page, and suggested that we code up one in Ruby on Rails, that would allow people to enter and edit information directly. As I will do almost any amount of work to get out of doing work, this seems like a good idea.
Our plan is to work on our local machines for a while, then deploy the system to my site when we have it going. As always, we’ll track our activities in a series of articles.
Chet downloaded Instant Rails and installed it. We have just run the sample apps and they seem to be working, so it appears we are ready to do something.
Monday: First Experiment
I had brought along my copy of the first edition of Thomas and Hansson’s Agile Web Development with Rails, and we began working through the initial example, which is little more than setting up Rails and making sure it works. We noticed right away that the version of Rails and Instant Rails that we had was not the same as in the book, so on our first trip back to the restroom at Borders in Brighton, we stopped at the computer shelves. Sure enough, there is a second edition. We bought both copies, because we pair program from opposite sides of the table.
We just worked through the Instant Gratification chapter, setting up a trivial little web app. As is our way when working through a tutorial, we change things around just a bit, which we think helps our understanding. Rather than just type in what the tutorial says, we type in similar things, and try little changes, to see what happens. That seems to help pound the ideas into our thick heads.
Everything worked just as described in the book, which is a credit both to the book authors, and to the developers of all the software that is packaged up in Instant Rails. It’s rare that some new open source thing comes down and actually works right out of the box. We were impressed and had a good time.
I won’t take you through the details of what we did – if you want those, grab the book and do it for yourself. Highly recommended as the best way to learn.
The Product Plan
Having finished Instant Gratification, we had a little time left before lunch, so we decided to plan our project a bit. We knew the domain: Ron’s Software Page, and had some requirements: Make it possible for the contributors to get their info onto the site in a timely fashion; accept that Ron is a poor web site admin; have fun.
We drew a few simple pictures of what the application might look like. There would be a page that listed a table of the software that’s available, with columns for the system name, contributor name, and so on, roughly like what’s on the site now. There would be some kind of Submit or Edit button that would let someone add a new item, or edit an existing one. Adding a new item would send me an email, and there would be an approval page where I could log in and check and approve entries. The idea there is to prevent spam or other kinds of vandalism.
We need security. Our cunning plan is to have the Add page include a user name and password field, which will be stored in the database record for the added item. The submitter defines his own name and password. If he wants to update, he has to put them in again. We think there might be a small login popup, or maybe they’ll just be fields on the existing pages.
And that’s our product vision. We talked for about ten minutes in drawing the cards, and of course we had chatted about the thing a bit on a preceding day, and we’ll keep talking. We mention this to highlight two things:
- We do actually recommend taking some up front time to plan the product and its design;
- We don't use but a tiny bit of up front time, preferring to do most of the planning and design as we go.
As we go forward with these articles, we’ll continue to mention our planning and design thoughts, as well as the development matters as well.
Tuesday: Second Experiment
Our mission today was to push forward a bit with Rails, setting up a small database. Chapter 5 of the book is an application for some kind of product ordering Depot. We decided to follow the flow of that chapter, but to put in information that relates to our application, again to get a sense of where things change.
Things mostly went well, until we got to page 56 in Chapter 5.. And that point, my copy of the book went from page 56 to page 25. Not as convenient as it might have been. I assume that this was Andy’s revenge for not buying the copies direct. Borders was nice about it and promised to get a new copy in right away and meanwhile I just let Chet read to me.
I was going to switch my copy for his but it turns out Chet had written his name in his copy as soon as he found out that mine was defective. That wasn’t very nice of him, but it’s just what you’d expect. Oh well, soon we’ll be into the part of my copy that has the right pages.
We ended Tuesday with a single dataset that represents a sketch of the software table, with a few records and a few validations put on the data. We’ve done the first two migrations suggested in the Depot part of the book, and so far so good.
Assessment So Far
We’re happy to be working with Ruby again. It is lots more fun than Java or C#. Of course, using Rails as we are, it’s not much like Ruby so much as using the Rails domain language but that’s OK too. It will be interesting to see how that shapes up.
In addition, we’re a bit concerned because we haven’t written any tests yes. On the other hand, we haven’t really written any code yet either! We’ll keep pressing on.
Wednesday: Still More
Wednesday we pressed on with the demo in the book, always modifying things to fit our application ideas. Everything continues to go smoothly with the tutorial, which is a real compliment to the authors. We plugged in my CSS file, though we have not started to use its tags and don’t have all the graphics files on Chet’s machine.
In addition, we worked a bit with the “Cart” mechanism of the tutorial, using that basic code to experiment with ways of selecting objects to appear on a cart page. In our app, the objects are descriptions of software packages for the page, and the cart will be an edit page for the contributor to enter and edit his own entries. (Recall that all this is precipitated by the fact that I am very slow at getting around to updates on the page.)
At every point along the way, we are choosing steps to take, and modifications to the main flow of the tutorial, to learn things we want to know, and to begin to drill things into our heads. So far, it seems that the tutorial is answering all our questions, but not in the order we have them. This is always the way when we use a framework: its model of how to do things doesn’t fit into our existing thought processes quite right.
In the case of Rails, there’s a very clear division of responsibility between Model, View, and Controller (and a few other components), but we haven’t quite got the hang of what goes where, so we look at two or three files before finding the one we need to edit. That will come with familiarity: we only have something under six hours of experience so far!
Thursday: And Yet More
Thursday our mission was to edit a record and put it back. Following the cart model from the tutorial, and bending things around a bit, we got a couple of our software records on a page, with editable fields. We added a save button and a save command and Voila! nothing happened. The record was not changed. After some digging around, we put an if statement around the call to save to see if it was failing and in fact it was. The issue, of course, was that you don’t “save” and existing record, you “update” it. Changing save to update made it work.
Beyond that, we fiddled around with linking the pages together, mostly just trying to get a sense for how redirects work in Rails, and a sense of what the site’s pages should look like.
Another session’s work completed, we treated ourselves to sandwiches at Amer’s Deli, where we were working anyway.
Friday: Port the App
We think it’ll be better to do our actual work on this app on my machine, since it has all the graphics and CSS and whatnot for my site. So Friday we made things work on my machine. There were only a couple of real issues.
Instant Rails was installed on my machine but had not been tested. We moved the files over and got some strange message that sounded like a version incompatibility with Ruby. That reminded us that it was necessary to change the path statement on my machine to point to Instant Rails’s copy of Ruby, not whatever old one I had lying around. We did that and moved on.
When we tried to run the migrations to put the DB on my machine, we were told that we didn’t have a database. There must have been a step somewhere that we didn’t remember but a little fiddling around got the database created and then the migrations ran just fine, albeit very slowly. It is possible that a lock was hanging somewhere. I killed some tasks and finally the migration finished.
The app seemed to work but of course there was no data. We created a record and now our little experiment runs on my machine as well as Chet’s.
Results So Far
In little more time than it took me to write this article, surely less than eight hours of work, we have completed a Ruby on Rails spike. We based it on an existing tutorial in the excellent Agile Web Development with Rails book, but we tuned the work to our own concerns and needs. We skipped parts of the tutorial where we already felt we had a handle on the topic, or that it could be deferred. We were always trying to follow the tutorial’s basic flow, but to be steering toward areas where we had special interest or questions.
There’s always a balance to be found when doing a spike, whether you follow a tutorial or just your own nose. There’s value to digging into something interesting, but it can be a time-eater, and spikes should be short. There’s value to skipping area where you are confident, but there may be important discoveries in places we don’t look.
It’s probably tempting for someone new to spikes to ask for a set of rules or guidelines on what to do and what to skip when spiking. Perhaps someone wiser than we are can write those rules, but my advice is simply to keep an eye on the time, decide what to look at and what to skip, and to pay attention to what happens. That last is important. If we pay attention to our decisions and how they turn out, we’ll tend to make better decisions. At least I hope so.
As we go forward in this series of articles, I’ll bet we run across something that turns out to be hard, or where we “should” have known something, and “if only we had read page 86” everything would have been so much better. Yeah, well. There are too many pages and too little time, so adding a new rule that says “always read every page” or “always read page 86” just isn’t going to improve our results.
We may also run across a problem and only after solving it will we remember that that was discussed on page 97, and we skimmed that page and decided not to work through it. OK, deal with it. We can’t do all the work in the world getting ready to do our actual job.
In both these cases, which will arise again and again, my advice is to get over it and accept that we can’t do a perfect job. Pick the things we want to study, pay attention to the results, reflect a bit, and just let our growing intuition do most of the work, that’s my advice.
In this case, we learned a lot, we chose what we looked at using our best judgment, guided by what happened as we made mistakes. We’ll see how well we did in this spike, but my guess is we did pretty well.
Learnings and Concerns
We have only about a day’s work in this spike. However, it was a day’s work punctuated into chunks of two hours or less. Chet and I discussed this, and we think it makes a difference in at least two ways.
First, because we have the hard time limit of lunch time, we are very focused each day on getting something actually done. We are not comfortable with a session where was work and work and accomplish nothing. When that does happen – and sometimes it does – we always reflect on what we could have done to accomplish something, and usually we figure it out. Usually it is that we took too big a bite, that we felt early on that it was too big, and that we pressed on anyway.We redouble our intentions to keep things small. The two-hour session, including time to get drinks, chat with the other shop customers we recognize, and discuss world events, means that we are really honed to get a step forward in very little time. That’s very good.
Second, though, is the fact that our two-hour sessions are a day apart. That means that we have time to process what happened in the previous session, and we usually reflect a bit, both after the session, and before the next one. We set our direction based on a few minutes’ discussion of what we learned. Reflection is always powerful and we are in the habit of doing it often. But our two-hour session, punctuated by 22 hours of something else, make for a bit of gelling. Every morning, at least one of us will have some new insight or notion about what happened the previous session.
It’s hard to know what impact this has on our work. On the one hand, we lose some continuity and have to be retrained every day. On the other hand, we have time for things to bubble up overnight. Maybe it balances out – or maybe one way or the other is clearly better. We don’t really know, because we only do things in our two-hour sessions.
One thing, though, we are very sure of. Our focus on getting something done every couple of hours is very valuable. When working in a single day, we might pay less attention to getting things done every couple of hours. We think that would be bad: we would get into the weeds, at least sometimes, and overall we’d get less done.
What does this suggest for day to day work? It’s hard to be sure, but between our long-standing observation that ten minutes between running tests is just about the outer limit of reason, and this observation about finishing a little story every couple of hours, there seems to be a consistent pattern. Smaller is better. Done is better. Smaller and done – that’s wonderful.
We need to decide whether to throw this spike away. This sort of thing always comes up at the end of a spike. We’re preprogrammed to plan to throw it away. Still, it works. However we agreed last week that going through it again would probably help us understand what the heck happened. Besides, it’s not our code: we copied a lot of it from the book. That’ll never do. So, we’ll start over.
Now. What shall we start over to do? I’ll discuss that in the next article. Let me get this one out there so you can start reading.