The Building of Jetrecord: Episode 2: Tell Me a Story
Sketches are quick, dirty, and cheap and that’s exactly how you want to start out. Draw stuff. Scrawl stuff. Boxes, circles, lines. Get your ideas out of your head and onto paper. The goal at this point should be to convert concepts into rough interface designs. This step is all about experimentation. There are no wrong answers. — From Idea to Implementation — Getting Real
In the last episode I talked about high level goals for the project and I created a framework of rules for myself in order to help me make decisions. In this episode I’m going to follow one of the rules I created for myself:
11. Each feature must begin with a story discussing the feature and its impact, followed by sketches of APIs and GUIs, followed by test coverage, followed by implementation.
Cue film.
Download (right-click and save) QuickTime MOV (39 Mb) | QuickTime iPod MP4 (8 Mb) | QuickTime SMIL with captions (39 Mb) [Note: you must choose to open the SMIL file with QuickTime]
Am I Building the Right Thing?
One of the questions we ended with last time was, “How do I know that what I’m building is what people really want?” The answer is: ask them.
I’m going to follow a principle from Extreme Programming that says you should have a customer on site with you as you build. If you can’t get a real customer, one of you has to play the role of Customer. That means I’m going to play the customer for my own application.
Is this legal? Yes and no. Under ideal circumstances the customer should be someone who is not a developer because features are a business decision, not a programming decision. Really, it should be the client paying for the engagement or, in the case of retail software, someone from the business side of your organization who is familiar with the domain and the needs of your customers. By playing both roles there’s a possibility that competing demands will cloud the judgment either of the Developer role or the Customer role.
At the same time, I’m a customer of Jetrecord. At least, I plan to be. So in a sense I’m building software for myself, so perhaps the two conflicts cancel each other out.
In any case I don’t have a choice.
Why Agile (or something like it)?
In my limited experience as a developer I’ve come to discover that programming is simply a conversation you have with your code. Just like writing an article, it may begin on one topic and end up on something completely different. Thinking about programming this way fits my personality and the way I learn new things. I love things that grow and take on a life of their own. I also like to look at the big picture several times during the course of a project. If I keep my head down for too long it’s easy to get lost in the details and pretty soon I’ve veered off course.
Certainly every circumstance is different and you have to adjust for the needs of the project. Agile, Extreme Programming, and the like don’t work for everything. When the choice is up to me, though, and the type of engagement is a good fit, I like the communication, freedom, and feeling of progress Agile affords.
And, of course, let’s remember that I’m not following Agile methodologies to the letter. I’m using methods that will help me get the project done reasonably and responsibly. I believe this follows the spirit of Agile, if nothing else.
The Basic Features
The customer’s job is to define the features of the application. Here they are in broad terms:
- Log flights
- Visualize flights and hours
- Export flights
I’m not going to worry about advanced and/or paying features yet. We’ll save those for later. If I don’t get these basic features right, there’s no point moving forward. These are the features that I, the Customer, believe bring the most value to the application at this point in the project.
Creating Stories
An Agile feature story is a “promise for conversation” according to Alistair Cockburn. That means, it’s important to get it down on paper so that we, the customer and developer, can talk about it at length later on. I’ll make sketches and write tests based on the stories I create. As for detail, I’m going to shoot for making each story completable in the span of one to two weeks, including tests.
Logbook Feature Stories
- Users can log flights via a simple form
- Users can log flights via a table/spreadsheet form, similar to paper logbooks
- Users can log flights by importing CSV files from other logbook software
- Users can log flights via authenticated API
- Users can see tallies of their flights and hours, separated into categories of experience and aircraft
- Users can export flights via RSS, JSON, XML, and a number of CSV formats based on the same logbook software supported by the import feature
Discussion
That’s enough to start. None of these have enough detail to tell me everything I need to know about the feature but they help me start conversations with the customer. They also tell me that there are some fundamental features that need to be developed in order support the ones listed. I would look at this list and begin discussing the following:
- What fields are included in a flight? Are any of them required?
- Please attach copies of example pages from a traditional paper logbook.
- Which third-party logbook software should be supported? Please attach examples of the CSV output created by the software.
Also, we’ve talked about flights, but flights belong to users. That means we need a system in place for managing users and their needs.
- What is required for someone to become a registered user?
- How are users identified? By ID, by login, by real name, by nickname?
- Do users manage themselves for things like registration, password changes and recoveries? How much intervention is required by admins?
- Can users delete their own accounts? And what happens to everything they’ve created on the site when they do?
- What about multi-user accounts? How are they managed? What happens to a user if the account they were associated with closes down?
User Feature Stories
- Users can self-register and manage every aspect of their account, including paying for services and deleting the account, without intervention by an admin. Since email is the only method used to communicate with members, email is required to signup. Users must verify their email in order to begin using their accounts. Users are identified on the web site by their nickname. Users should receive email notification upon successful signup.
- Users can login from the web site or from third party applications.
- When users delete their accounts, all of their flights are deleted, followed by any aircraft used (assuming they’re the only pilot of the aircraft), followed by any routes used (assuming they’re the only pilot of that route), followed by their user account and any associated files. Users should receive email notification that their account has been deleted.
- Accounts with more than one user have certain admin users who manage the account, including payment details. Admins can manage permissions for other members and invite and kick members.
- When multi-user accounts are deleted by an admin, associated users will have the option to continue paying for features at the same level, upgrade to higher paying options, downgrade to lower paying or free options with features removed, or have their accounts deleted.
Discussion
It looks like we need a fairly complicated user management system in addition to being able to log flights. Ideally, with a larger team, we could work on both at the same time. However, since it’s only me, and since I’m also the customer, I’ve decided that the user management system is the first thing I’ll do after setting up my development and production environments.
Sketches
Again, these are sketches. Not blueprints or wireframes. Not schematics or Photoshop comps. They have just enough detail to let me know what I’m building so I can begin creating HTML mockups, acceptance tests, and unit tests. Ideally, as the developer, I’m drawing these while seated next to the customer so we can make changes quickly and throw things away if need be.
Flight Forms
User Forms
User API
Inventory
At this point I should be able to take the sketches and start building the application using whatever language I choose. I had a great time using the Ruby on Rails framework to build version 1 and I’ve decided to use it again for version 2. It’s well-suited to handle an application of this type and the Ruby language is, for lack of a better word, fun.
These are the things I need to get going (note: gems are installed with RubyGems):
- Ruby
- RubyGems
- Ruby on Rails
- PostgreSQL (you can also use MySQL if you wish)
- ruby-pg gem (Ruby PostgreSQL interface)
- Note: I had to install with “gem install pg” instead of “gem install ruby-pg” to get the most recent version
- Find a gem for MySQL if you’re using that database
- RSpec Rails gem
- Cucumber gem
- Capistrano gem
- Git
Optional: Ruby on Rails comes with a simple web server that we can use for development purposes. However, I’m going to set up and practice using the server that I will use in production, even though the OS will be different:
- Apache
- Ruby Enterprise Edition
- Phusion Passenger (aka ModRails)
I’m not going to cover installation. I assume you can follow the instructions given on their respective web sites and that you know how to use Google. Assuming you’re going to follow along as I write code, if you’ve never worked with Rails before I recommend installing everything and working through any of the simple tutorials you can find on the web before continuing on.
Also, please note, from here on out I’m not going to talk about the topic of programming per se. If you’ve never programmed before, the rest of the series might be interesting to watch but otherwise might go over your head. Let me say, though, that there are hundreds of web-based tutorials that can teach you how to program. There are even some that use Ruby.
Coming Up in the Next Episode
I’m going to set up my Rails project and my Git source code repository. Then I’m going to make sure I can do an initial release. Until next time, cheers and happy flying.
Material You May Find Useful Related to This Episode
The Building of Jetrecord by Harry Love is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License. When code, text, or media in this series is not created by me and is not in the public domain I will provide links to their sources from which you can find their respective licenses and terms of use.
[...] Episode 2: Tell Me a Story, is out now. How do you know what you’re building is what people really want? Tags: videos Filed under: Business, Preflight [...]
Hey there,
First up, congrats on following Alistair’s concepts – I’ve been keeping up with his writings for ages and he has great stuff for light weight, fast dev concepts (yes, OK, agile :)
It’s interesting that you raise the issue of discussions with the client when it’s just you on your own. While nowhere near as good as having the client rep in the room with you while you’re working, perhaps this blog will help as you can outline your thoughts, issues and answers (as you already have been doing). We can then chip in comments and ideas that may help in what you’re doing.
Not as immediate as having someone there without, but certainly it helps get more than just your input. Even when you’re a client as well as developer, having input from those who aren’t doing the coding should help :)
NOTE: If you need something more immediate, how about recruiting a few representative users online and setting up a mailing list. You could then post concerns and questions there, then see what the virtual-client-rep responds with. You could also post your ideas and the answers you’d give so that the virtual-reps could respond with “That’s good” or “I like it, but…” :)
One final comment relates to Ruby and Ruby on Rails. Don’t forget to ensure that your design and implementation can meet the scaling needs you’re likely to have as JetRecord takes off. As I’m sure you’ve seen from Twitter and other reports on the ‘net, Ruby on Rails can have scaling hassles if it’s not designed right and doesn’t have good hardware behind it. Google for:
ruby on rails scaling issues
and see what you get – very handy information to consider now in the early days than later :)
Cheers,
Grant
Thanks, Grant. Those are some great points. It’s difficult to figure out the balance on a project like this because it’s not the same as having one client who’s paying for the whole thing. I have to walk the fine line between giving end users a say and thinking about the needs of the business. In the end I have to be the voice of all customers, even the ones who don’t speak up.
Given the small percentage of current users who voice an opinion, I’ll probably keep comments open on this site and also on the Jetrecord Blog. I’ll try to put designs out for comment there when I have things worth looking at.
As for Rails, scaling is kind of an inside joke in the Rails community. Rails (and Ruby) actually scale very well. There are several Rails sites that serve millions of users. As in most software, it’s the architecture and the implementation that will do you in, as was the case with Twitter until they hired some people who knew how to build what they needed. And they’re still using Rails.
Typically in a project with many users with different approaches to their use of the system, I’d go with a few key user reps rather than just one. Depends on the size of the team, project, etc. Of course, this is tricky for your project given the number of different approaches, the size of the team and the lack of co-location :)
I think you’re right that going with what *you* want to get things started & keep the project flowing is the way to go. Throw in this blog and the JetRecord blog to present concepts and solicit comments from the user base and you should get pretty good coverage.
Thanks for the comments re: Rails – indeed it is the design that’ll kill you – just wanted to be sure you were aware of the pitfalls so your design would be ready for scaling. Glad to see you’re well and truely on top of it (course you are – you’re a pilot – proper prior planning and research before a flight into the unknown :) :)
Actually, I’m not a pilot yet. See the About page on Jetrecord. But I like to think I’m getting better at planning and research all the time.