Ruby Red Bricks

Today in our end-of-week get together the team discussed treating requirements with a little less care than we currently do. Probably like a lot of places out there, we diligently enter our requirements into a tracking system (currently Mingle), schedule them for work, implement and test and then finally – if everything goes well – close them as part of a release..

..and then never look at them again.

Over time a lot of cruft gets built up – old requirements that may / may not be still relevant.. huge amounts of data that is pretty difficult to search through.. a big inventory of past work that could be considered – in the lean sense of the word – as waste, i.e. it provides little or no ongoing value.

The outcome of the meeting today was to allow requirements to go through their normal life-cycle, reach a final stage of user acceptance – and then be thrown away. We’re even considering going back to using just plain 3”x5” cards for recording requirements and then tearing them up once the work has been successfully completed from the clients’ perspective.

The argument for doing this is that the code and the application itself is the best documentation of an application’s functionality – any documentation should be derived from it and not from some abstract or alternative representation. This requires some discipline: when I say “code” I include test code. Specifically I mean using Behaviour Driven Development (BDD) and capturing the specification of an application in a form that is comprehendible by both developers and end-users alike.

Because we’re a Rails shop and use both RSpec and Cucumber we can translate requirements into executable specifications, e.g.:

Given that I am I new user
When I register a new account and enter my details
Then I will be emailed a welcome message advising how to activate my account

describe User
  it "MUST have a password longer than 6 characters" 
  it "MUST have a unique login id"

Once these are entered into the codebase, test code is written (and passes!) these become the canonical specifications for the application, the ultimate statement of what the application actual does and what constraints exist. Often during the course of development we’ll come across new requirements – or clarify existing ones. The neat thing about most BDD tools is they generally allow you to print out a text-only version – a document that can be cheaply and frequently presented to the customer detailing the actual and proposed features of the system to confirm that development is on the right course, with the right understanding of what the customer wants.

Naturally there are other ways of recording requirements that can’t be covered by BDD. One important artifact we use all the time is the Wireframe – but again this is a temporary artifact. Once the app has been implemented the best definition of its look and feel is the application itself.

Some customers will require more permanent requirement artifacts. That’s fine, we can do that to satisfy contracts – but it will probably be the exception to the rule. We may need to create additional artifacts in different situations. Again fine, but let’s start with a simple model first and see what we need to do to complicate things.

OK, I’m tired.. and it’s been a long week. But I think that makes sense. Yeah?

Hey folks

Another proto-novel is now online. I’ve been loathe to put this one up for a couple of reasons. When I read the first few pages of this out at a writer’s group meeting years ago you could have heard a pin drop. Eventually a little old lady piped up with “it made me feel sick”. At the coffee break she later said “I guess you were trying to make me feel sick, so I guess it works as a piece of writing” – which I think was terribly nice of her to say.

I’m not convinced that it does work, but it’s out there now and we’ll see how it progresses. I didn’t want it to be the first piece I put up because I didn’t want the content to distract from what I’m trying to achieve in terms of using Rails as a content management system.

Keeping in with the idea that Rails is a language for expressing web sites, I’ve had to extend the language with a helper. I got sick of typing <%= link_to 'next page', :action => 'next_page' %> – indeed as I said I would – so I built a simple helper to remove the repetition. So now each page ends with a <%= link_to_page 'next_page' %>. The convention is that text is the same as the action, with underscores replaced with spaces. I’ll be in trouble if the text varies from this, but it hasn’t so far and I can always fall back to the old link_to approach.

As with The Young Person’s Guide To Time Travel, the code is up on github. The website for the writing can be found here:

http://thispurpleworld.com:

And before you say it, yes I am a sick puppy.

OK, time for that tricky second page.. the bane of all pretentious writerly types out there in the blagosphere (hello brothers and sisters).

I had a bit of fun trimming all the superfluous verbiage from the original – I’m sure there’s a simpler way of saying that. There’s the implicit irony of using the “Hemingway” layout – I’m keen to slim this so-called novel down as much as possible, let it travel light and fast. As it happens I’ve been reading ‘The Old Man and the Sea’. Terse? Ernest was a C coder!

Joking aside, I do actually want you to read this story and enjoy it – I’d like it to be a ‘page turner’, as much as an online novel can be. An interesting convention I’ve played with before is to use the last few words on a page as the link to the next. It’s the closest approximation to a page turning experience I can think of.. when you come to the end of the page the last phrase is the trigger for going to the next page.. the loading time the little mental breath you take when you turn the page..

The implementation is deadly simple:

I’m using a link_to but it may get converted into a helper method later. This style of navigation may become unwieldy past a few pages, but we’re not there yet. As you may have noticed, I’m deferring all the hard stuff until I actually know I need to worry about it.

OK, we’re a few hundred miles away from making a general purpose CMS. But the spec has changed.

Have a look, tell me if it works for you:

http://guidetotimetravel.com

Hi reader

Well, seeing as most of the traffic to this site seems to be from people looking for ideas on how to use Rails as a CMS I’ve got this basic pointer:

http://www.browsercms.org/

It’s pretty sexy. I’m in no way affiliated with the project – and that’s probably a good thing. If you want to get a CMS up and running quickly and be able to administer it with a minimum of fuss, this could very well be the thing for you.

On the other hand, if you’re still keen to see how far we can take this concept that Rails is effectively a language for describing a web site then my little project may be of interest. Fair warning.. it’s a bit odd, and might get suspended at any point if work or other pressures come to bear. With that in mind, let me introduce you to:

The Young Person’s Guide To Time Travel

Back in my uni days I started writing a novel. I don’t think that’s particularly unusual – many of us started writing a novel in uni. Some of us, like my old mate Penni Russon actually went on and got a novel published, but I chose to take a more traditional path and squash any idea of a successful career in writing under the rest of the pile of unrealised dreams and ambitions.

A while ago I blew the dust off a few old CD-ROMs and had a good look at my old writing. None of it was going to set the world on fire, but there was the odd spark – so I decided to give it another crack. Getting published is less of an issue as just getting something out there, so publishing online is an option. Since talking to Corey Doctorow at the Melbourne Writer’s Festival a few years back I’ve been interested in how the Creative Commons model provides a mechanism for writers to get their content out there without screwing their audience. I also want to live in a world where there’s a more direct dialogue between content creators and consumers. Apologies for (a) the implicit lefto-pinko-free-as-in-freedom sentiment and (b) name-dropping. For what it’s worth, I thought Corey was a decent guy.. though like many Canadians he has a funny-shaped head.

OK, enough of the back-story. Here are my basic requirements for a content management system:

• I don’t have time to learn a new tool.

Drupal, Radiant, etc may be great but it’s another “language” I have to grok. I understand and enjoy the conventions of Rails – that’s all I want to have to know. When it comes time to customise I don’t want to have to work around a different set of conventions or code.

• I don’t have time .. period.

I work full-time, have a family and a million other things in my life. The CMS needs to get out of my way and let me write. Anything clunky or complex is useless.

• The CMS must support my tool set.

The novel will get written in small increments, in a very ‘agile’ sense (release early, refactoring, etc). It’s very similar to how I might write code. I expect to be able to use text editors on my laptop, use version control systems, preview work locally, test it.. just like I would with an application. In my head, the novel is just a different kind of application.

Some of this was covered in the original ‘Ruby on Rails based CMS’ post from way back. I’ll be revisiting the points from that article as we go, though not right now. My immediate aim is just to get something up and running as quickly as possible – and the simplest thing I can possibly do is to create a new Rails app, create a controller for serving up pages and drop the opening page in.

You can see the code here:

http://github.com/ferrisoxide/guide_to_time_travel/tree/master

There’s plenty to do – I’ve been incredibly lazy and not bothered to secure or structure the code at all. That can come later. The objective was to get something live as quickly as possible. I nicked the Hemingway layout from Warpsire, though I’ll need to get it looking a bit neater. Getting the actual site up and running simply a matter of shelling in an running git clone. From go to whoa took maybe all of an hour, spread over a few days, with the first page available here:

http://guidetotimetravel.com/

One gotcha – Dreamhost’s Passenger setup doesn’t seem to use your local gems, so if you are wanting to use Rails 2.3.2 you need to install it into your local gem repo and run rake rails:freeze:gems. It’s quite odd, as rails -v will return the 2.3.2 version number if it’s installed but I’m guessing Passenger looks at the version of Rails in the official Dreamhost repo (v 2.2.2 at the time of writing). Makes sense.

All good. Now we come to the difficult part for all aspiring part-time novelists: the tricky second page. But that’s a whole new blog post. ‘Til next time…

Cheers Tom

Now for something completely different, a few weekends ago I whacked out a proposal for a simple process control architecture based on REST… as you do. You can read about it here:

http://www.rest-pca.org

I’m not really sure what I’m planning with this – it’s more an ongoing conversation with an old mate from my process control days. Nah.. big fat lie.. I really want to build a SCADA system to run something like this:

More than a weekend project – but what a sweet, sweet dream to have.

If you’re in Adelaide (South Australia) and have experience in Rails, Katalyst are currently looking for developers. We’re a small team, specializing in custom web development and interactive media. You can get a bit of an idea of what we do from the Katalyst website.

If you’re interested, send a CV to jobs@katalyst.com.au.

We have some very old, heritage listed lifts at work. Some days they function, many days they don’t. When the lifts break down the maintenance guy leaves a note on the door – usually annotated within hours by some bored or frustrated tenant or visitor to the building.

As amusing as “fuck me” might be, I really felt like a bit of reality tweaking was in order. Small things amuse small minds.. and I have a tiny, peanut-sized mind. Plus it’s my last week in the building, so I may as well have some fun:

Anything to make other people’s lives a little bit weirder…