Archive for October, 2008

John Travolta

I have no point. I just wanted to say the name.

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:

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

Extreme Programming Installed by Ron Jeffries

Designing Interfaces by Jenifer Tidwell

Universal Principles of Design by William Lidwell

Moleskine Storyboard Notebook Pocket

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.

The Building of Jetrecord: Episode 1: The Tabula Rasa of Doom

We were out at our family cabin in Bolinas, and he was at the kitchen table close to tears, surrounded by binder paper and pencils and unopened books on birds, immobilized by the hugeness of the task ahead. Then my father sat down beside him, put his arm around my brother’s shoulder, and said, “Bird by bird, buddy. Just take it bird by bird.” –Anne Lamott

I don’t think any of us ever realizes the hugeness of the task until we sit down with our materials and attempt to make sense of it all, even though the whole making-order-out-of-chaos thing is highly overrated in my opinion. Nevertheless, that’s what I’m going to do here in this series. I’m going to take a seemingly simple task–building an online logbook for pilots–expose the underbelly, cut it apart, and then put it all together into a fantastic, cohesive product that everyone will love, including me and you and every pilot you know.

Why? Because I believe we are created to do two things: experience pain and build things. Sometimes these are one and the same. I hate to admit right from the start that this is a task to which I feel compelled, by which I feel repulsed, and about which I feel nonplussed but apparently we’re in a new age of transparency so I’m starting with me, as Michael Jackson would say. I both love and hate computers and projects. And it always happens that about the time I’ve finished a web project I’ve forgotten all about this crummy beginning stage and am strangely excited to do it all over again.

Cue film.

Download (right-click and save) QuickTime MOV (49 Mb) | QuickTime iPod MP4 (7 Mb) | QuickTime SMIL with captions (49 Mb) [Note: you must choose to open the SMIL file with QuickTime]

It Begins Like This

I’m building version 2 of an online logbook for pilots called Jetrecord. This is my attempt to record and share the process.
This is not an exercise (please place your hands inside the yellow circles); it’s the process of building a genuine application that is already live on the web. What you see here is what will be released for version 2. I’m hoping that by sharing something real you’ll be inspired to create your own projects and you’ll see what it’s like for one developer to wade through this stuff.
As far as sharing goes you are free to take the code, the text of this series, and the videos and reuse, repurpose, and remix them under the terms of the Creative Commons Attribution-Share Alike 3.0 United States License. More details are at the end of this post.
My other hope is that we can learn from each other. I am not an expert, as will become more apparent as the series goes on. Please contribute your knowledge in the comments. Can something be improved? Do you have a suggestion or a critique? I want to hear it. Please keep it constructive, though. Shuriken are not allowed.
If you’d like to contact me by email concerning the series, use harry@harrylove.org.

The Scope of the Series

The process of creating a web application from start to finish involves several subjects and my plan is to explore breadth rather than depth. That is, I’m going to talk about whatever will help me complete the project and I’ll mostly concentrate on the places where subjects overlap. If I don’t explain things in enough detail, I apologize. The truth is I may not know enough about a subject to explore it in depth. I’ll try to point you to the places I’m getting my information. Don’t hesitate to speak up if you’d like me to say more about a particular topic. If I have something more to say, something worth creating a new episode for, I may just do it. Otherwise, of course, I’ll point you to my sources.

Let’s Start with Questions, Goals, and Rules

I’m going to start this project the same way I would approach an essay, article, or presentation, by asking questions and then stating goals and rules. You don’t have to do it this way. This is how I do it because it works for me. I’m going to say that just once. It applies to everything I’m going to do from here on out but I don’t want to bore you to death by repeating myself every episode (there’s an important programming principle in there somewhere).

Questions

What do I want to build?
- I want to build a web-based logbook for pilots.
Why do I want to build it?
- I love aviation, data, and the connections made when data cross paths.
- I am building this because it’s a product that I myself will use.
- I have surveyed the available logbook software, both desktop- and web-based, and have not seen any that use the same approach to building logbooks that I’m using to build Jetrecord.
- I believe this is a product that can work in concert with existing desktop- and web-based products.
Is this an art project or do I need to consider my audience?
- It’s both, but I am building this product for public consumption so I need to consider my audience.
Who are the primary people groups in my audience?
- Pilots
- Air and ground crew
- Affiliates
- Aviation buffs
- Their family and friends
Do these people need this software? Why should they care?
- Pilots must show proof to governing authorities that they have obtained any necessary knowledge and flying experience. Logbooks have been the standard method for recording flying experience for several decades.
- The second two groups may have business concerns with the logbooks but will otherwise not need a logbook of their own.
- The last group is important to consider because the entry of each flight will be made public, suitable for sharing with family and friends in the same way that family and friends share news, pictures, and video through blogs.
Can I afford to build it?
- The operating system, programming language, web framework, web server, and database server I am using are all available under open source licenses.
- I have a computer that is well suited for the purpose of building a web application using this software.
- I have some good software to edit the code and some to create and edit graphics for the web site.
- The web application is currently hosted at Joyent using the $125 per month Accelerator option and there is room to grow using the current resource limits; there are both horizontal and vertical scaling options available at Joyent should the application outgrow its resources.
- My company bank account is free but I may need to switch to a paying account if Jetrecord becomes very popular to the point of making more than a few hundred deposits per month.
- The merchant account and credit card processing fees per month have been quoted from a reputable business at less than $50 per month.
- The cost of doing business in Longmont, Colorado as a Sole Proprietor is a small annual fee.
- I have access to help in preparing my taxes.
Can I afford to maintain it and keep it running for years to come?
- If the current ongoing fees are any indication, the answer is yes. Obviously, in the best case scenario, if Jetrecord suddenly jumps from 1,000 users to 100,000 I will need to upgrade the servers a bit. I may also need additional partners or staff to help manage the workload.
Do I have enough domain knowledge to build it?
- I have enough knowledge about aviation and logbooks to make a good product.
- I have already built version 1 and it has been well received by the pilots who use it, including both general and commercial pilots.
Do I have access to information about the domain?
- I have access to the FAA’s regulations concerning logbooks through their web site and also via the FAR/AIM book.
- There are many web sites, magazines, and books that focus on issues concerning pilots and aviation.
Do I have access to customers and are they willing to teach me about the domain?
- I have access to the current users of the product.
- I am in contact with several pilots through Twitter and myTransponder.
- I have spoken with several pilots over the phone who have expressed interest in helping me.

Goals

Succinctly and broadly, what is the desired end state? For example, the goal of basketball is to have more points than your opponent at the end of the allotted time for the game.

The logbook is the key application, regardless of any related features.
It must be as easy as possible to get data into and out of the system both from within the Jetrecord web site and from the developer API.
It must be as useful as possible to as many classifications of pilots as possible, but focus on general and commercial aviation.

Mantra

Pilots Aren’t Robots Yet!

Rules

I’m writing some rules for myself that will serve as a guide for the decisions I make. They are written with this project in mind only.

Rules should help us make decisions; this is the only criteria for adding a rule.
Modify or discard any rules that are not helpful.
Use the best design principles we know how to use and spend time researching concepts we are unfamiliar with.
Make forward progress; no product is perfect.
Follow the spirit of Agile methods for software development; remember rule #2 above
Keep documentation in the source code except where sensitive information may compromise security or business secrets.
Documentation is for developers and is an interface into the system; design it well.
Everything should be added to the source control repository unless there is a good reason not to.
Code that can be extracted into a shared library (gem) or plugin should be.
Favor gems, plugins, other libraries, and framework code to writing our own unless there is a good reason not to.
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.
Metrics should be built into the project early and often.
Questions drive the need for answers which drive the need to record data, not the other way around.
Build for data access first and GUI display second.
Build for universal access.
Build for progressive enhancement.
Browsers must prove their worth to be included in our support; mainstream use is not proof in and of itself.
See also Matthew Moore’s Ruby on Rails Code Quality Checklist; remember rule #2 above

Coming Up in the Next Episode

Next I’m going to write a brief outline of the basic application. I’m also going to sketch the application on paper and make a list of parts I need to get started. I hope you’ll join me. You can subscribe to the RSS feed in order to be notified when the next episode is up. I have also created a table of contents page for this series. Until next time, cheers and happy flying.